8051 lines
380 KiB
Plaintext
8051 lines
380 KiB
Plaintext
This is gdb.info, produced by makeinfo version 6.5 from gdb.texinfo.
|
||
|
||
Copyright (C) 1988-2020 Free Software Foundation, Inc.
|
||
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
any later version published by the Free Software Foundation; with the
|
||
Invariant Sections being "Free Software" and "Free Software Needs Free
|
||
Documentation", with the Front-Cover Texts being "A GNU Manual," and
|
||
with the Back-Cover Texts as in (a) below.
|
||
|
||
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
|
||
this GNU Manual. Buying copies from GNU Press supports the FSF in
|
||
developing GNU and promoting software freedom."
|
||
INFO-DIR-SECTION Software development
|
||
START-INFO-DIR-ENTRY
|
||
* Gdb: (gdb). The GNU debugger.
|
||
* gdbserver: (gdb) Server. The GNU debugging server.
|
||
END-INFO-DIR-ENTRY
|
||
|
||
This file documents the GNU debugger GDB.
|
||
|
||
This is the Tenth Edition, of 'Debugging with GDB: the GNU
|
||
Source-Level Debugger' for GDB (GDB) Version 9.2.
|
||
|
||
Copyright (C) 1988-2020 Free Software Foundation, Inc.
|
||
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
any later version published by the Free Software Foundation; with the
|
||
Invariant Sections being "Free Software" and "Free Software Needs Free
|
||
Documentation", with the Front-Cover Texts being "A GNU Manual," and
|
||
with the Back-Cover Texts as in (a) below.
|
||
|
||
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
|
||
this GNU Manual. Buying copies from GNU Press supports the FSF in
|
||
developing GNU and promoting software freedom."
|
||
|
||
|
||
File: gdb.info, Node: Architecture-Specific Protocol Details, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol
|
||
|
||
E.5 Architecture-Specific Protocol Details
|
||
==========================================
|
||
|
||
This section describes how the remote protocol is applied to specific
|
||
target architectures. Also see *note Standard Target Features::, for
|
||
details of XML target descriptions for each architecture.
|
||
|
||
* Menu:
|
||
|
||
* ARM-Specific Protocol Details::
|
||
* MIPS-Specific Protocol Details::
|
||
|
||
|
||
File: gdb.info, Node: ARM-Specific Protocol Details, Next: MIPS-Specific Protocol Details, Up: Architecture-Specific Protocol Details
|
||
|
||
E.5.1 ARM-specific Protocol Details
|
||
-----------------------------------
|
||
|
||
* Menu:
|
||
|
||
* ARM Breakpoint Kinds::
|
||
|
||
|
||
File: gdb.info, Node: ARM Breakpoint Kinds, Up: ARM-Specific Protocol Details
|
||
|
||
E.5.1.1 ARM Breakpoint Kinds
|
||
............................
|
||
|
||
These breakpoint kinds are defined for the 'Z0' and 'Z1' packets.
|
||
|
||
2
|
||
16-bit Thumb mode breakpoint.
|
||
|
||
3
|
||
32-bit Thumb mode (Thumb-2) breakpoint.
|
||
|
||
4
|
||
32-bit ARM mode breakpoint.
|
||
|
||
|
||
File: gdb.info, Node: MIPS-Specific Protocol Details, Prev: ARM-Specific Protocol Details, Up: Architecture-Specific Protocol Details
|
||
|
||
E.5.2 MIPS-specific Protocol Details
|
||
------------------------------------
|
||
|
||
* Menu:
|
||
|
||
* MIPS Register packet Format::
|
||
* MIPS Breakpoint Kinds::
|
||
|
||
|
||
File: gdb.info, Node: MIPS Register packet Format, Next: MIPS Breakpoint Kinds, Up: MIPS-Specific Protocol Details
|
||
|
||
E.5.2.1 MIPS Register Packet Format
|
||
...................................
|
||
|
||
The following 'g'/'G' packets have previously been defined. In the
|
||
below, some thirty-two bit registers are transferred as sixty-four bits.
|
||
Those registers should be zero/sign extended (which?) to fill the space
|
||
allocated. Register bytes are transferred in target byte order. The
|
||
two nibbles within a register byte are transferred most-significant -
|
||
least-significant.
|
||
|
||
MIPS32
|
||
All registers are transferred as thirty-two bit quantities in the
|
||
order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32
|
||
floating-point registers; fsr; fir; fp.
|
||
|
||
MIPS64
|
||
All registers are transferred as sixty-four bit quantities
|
||
(including thirty-two bit registers such as 'sr'). The ordering is
|
||
the same as 'MIPS32'.
|
||
|
||
|
||
File: gdb.info, Node: MIPS Breakpoint Kinds, Prev: MIPS Register packet Format, Up: MIPS-Specific Protocol Details
|
||
|
||
E.5.2.2 MIPS Breakpoint Kinds
|
||
.............................
|
||
|
||
These breakpoint kinds are defined for the 'Z0' and 'Z1' packets.
|
||
|
||
2
|
||
16-bit MIPS16 mode breakpoint.
|
||
|
||
3
|
||
16-bit microMIPS mode breakpoint.
|
||
|
||
4
|
||
32-bit standard MIPS mode breakpoint.
|
||
|
||
5
|
||
32-bit microMIPS mode breakpoint.
|
||
|
||
|
||
File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Architecture-Specific Protocol Details, Up: Remote Protocol
|
||
|
||
E.6 Tracepoint Packets
|
||
======================
|
||
|
||
Here we describe the packets GDB uses to implement tracepoints (*note
|
||
Tracepoints::).
|
||
|
||
'QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]'
|
||
Create a new tracepoint, number N, at ADDR. If ENA is 'E', then
|
||
the tracepoint is enabled; if it is 'D', then the tracepoint is
|
||
disabled. The STEP gives the tracepoint's step count, and PASS
|
||
gives its pass count. If an 'F' is present, then the tracepoint is
|
||
to be a fast tracepoint, and the FLEN is the number of bytes that
|
||
the target should copy elsewhere to make room for the tracepoint.
|
||
If an 'X' is present, it introduces a tracepoint condition, which
|
||
consists of a hexadecimal length, followed by a comma and
|
||
hex-encoded bytes, in a manner similar to action encodings as
|
||
described below. If the trailing '-' is present, further 'QTDP'
|
||
packets will follow to specify this tracepoint's actions.
|
||
|
||
Replies:
|
||
'OK'
|
||
The packet was understood and carried out.
|
||
'qRelocInsn'
|
||
*Note Relocate instruction reply packet: Tracepoint Packets.
|
||
''
|
||
The packet was not recognized.
|
||
|
||
'QTDP:-N:ADDR:[S]ACTION...[-]'
|
||
Define actions to be taken when a tracepoint is hit. The N and
|
||
ADDR must be the same as in the initial 'QTDP' packet for this
|
||
tracepoint. This packet may only be sent immediately after another
|
||
'QTDP' packet that ended with a '-'. If the trailing '-' is
|
||
present, further 'QTDP' packets will follow, specifying more
|
||
actions for this tracepoint.
|
||
|
||
In the series of action packets for a given tracepoint, at most one
|
||
can have an 'S' before its first ACTION. If such a packet is sent,
|
||
it and the following packets define "while-stepping" actions. Any
|
||
prior packets define ordinary actions -- that is, those taken when
|
||
the tracepoint is first hit. If no action packet has an 'S', then
|
||
all the packets in the series specify ordinary tracepoint actions.
|
||
|
||
The 'ACTION...' portion of the packet is a series of actions,
|
||
concatenated without separators. Each action has one of the
|
||
following forms:
|
||
|
||
'R MASK'
|
||
Collect the registers whose bits are set in MASK, a
|
||
hexadecimal number whose I'th bit is set if register number I
|
||
should be collected. (The least significant bit is numbered
|
||
zero.) Note that MASK may be any number of digits long; it
|
||
may not fit in a 32-bit word.
|
||
|
||
'M BASEREG,OFFSET,LEN'
|
||
Collect LEN bytes of memory starting at the address in
|
||
register number BASEREG, plus OFFSET. If BASEREG is '-1',
|
||
then the range has a fixed address: OFFSET is the address of
|
||
the lowest byte to collect. The BASEREG, OFFSET, and LEN
|
||
parameters are all unsigned hexadecimal values (the '-1' value
|
||
for BASEREG is a special case).
|
||
|
||
'X LEN,EXPR'
|
||
Evaluate EXPR, whose length is LEN, and collect memory as it
|
||
directs. The agent expression EXPR is as described in *note
|
||
Agent Expressions::. Each byte of the expression is encoded
|
||
as a two-digit hex number in the packet; LEN is the number of
|
||
bytes in the expression (and thus one-half the number of hex
|
||
digits in the packet).
|
||
|
||
Any number of actions may be packed together in a single 'QTDP'
|
||
packet, as long as the packet does not exceed the maximum packet
|
||
length (400 bytes, for many stubs). There may be only one 'R'
|
||
action per tracepoint, and it must precede any 'M' or 'X' actions.
|
||
Any registers referred to by 'M' and 'X' actions must be collected
|
||
by a preceding 'R' action. (The "while-stepping" actions are
|
||
treated as if they were attached to a separate tracepoint, as far
|
||
as these restrictions are concerned.)
|
||
|
||
Replies:
|
||
'OK'
|
||
The packet was understood and carried out.
|
||
'qRelocInsn'
|
||
*Note Relocate instruction reply packet: Tracepoint Packets.
|
||
''
|
||
The packet was not recognized.
|
||
|
||
'QTDPsrc:N:ADDR:TYPE:START:SLEN:BYTES'
|
||
Specify a source string of tracepoint N at address ADDR. This is
|
||
useful to get accurate reproduction of the tracepoints originally
|
||
downloaded at the beginning of the trace run. The TYPE is the name
|
||
of the tracepoint part, such as 'cond' for the tracepoint's
|
||
conditional expression (see below for a list of types), while BYTES
|
||
is the string, encoded in hexadecimal.
|
||
|
||
START is the offset of the BYTES within the overall source string,
|
||
while SLEN is the total length of the source string. This is
|
||
intended for handling source strings that are longer than will fit
|
||
in a single packet.
|
||
|
||
The available string types are 'at' for the location, 'cond' for
|
||
the conditional, and 'cmd' for an action command. GDB sends a
|
||
separate packet for each command in the action list, in the same
|
||
order in which the commands are stored in the list.
|
||
|
||
The target does not need to do anything with source strings except
|
||
report them back as part of the replies to the 'qTfP'/'qTsP' query
|
||
packets.
|
||
|
||
Although this packet is optional, and GDB will only send it if the
|
||
target replies with 'TracepointSource' *Note General Query
|
||
Packets::, it makes both disconnected tracing and trace files much
|
||
easier to use. Otherwise the user must be careful that the
|
||
tracepoints in effect while looking at trace frames are identical
|
||
to the ones in effect during the trace run; even a small
|
||
discrepancy could cause 'tdump' not to work, or a particular trace
|
||
frame not be found.
|
||
|
||
'QTDV:N:VALUE:BUILTIN:NAME'
|
||
Create a new trace state variable, number N, with an initial value
|
||
of VALUE, which is a 64-bit signed integer. Both N and VALUE are
|
||
encoded as hexadecimal values. GDB has the option of not using
|
||
this packet for initial values of zero; the target should simply
|
||
create the trace state variables as they are mentioned in
|
||
expressions. The value BUILTIN should be 1 (one) if the trace
|
||
state variable is builtin and 0 (zero) if it is not builtin. GDB
|
||
only sets BUILTIN to 1 if a previous 'qTfV' or 'qTsV' packet had it
|
||
set. The contents of NAME is the hex-encoded name (without the
|
||
leading '$') of the trace state variable.
|
||
|
||
'QTFrame:N'
|
||
Select the N'th tracepoint frame from the buffer, and use the
|
||
register and memory contents recorded there to answer subsequent
|
||
request packets from GDB.
|
||
|
||
A successful reply from the stub indicates that the stub has found
|
||
the requested frame. The response is a series of parts,
|
||
concatenated without separators, describing the frame we selected.
|
||
Each part has one of the following forms:
|
||
|
||
'F F'
|
||
The selected frame is number N in the trace frame buffer; F is
|
||
a hexadecimal number. If F is '-1', then there was no frame
|
||
matching the criteria in the request packet.
|
||
|
||
'T T'
|
||
The selected trace frame records a hit of tracepoint number T;
|
||
T is a hexadecimal number.
|
||
|
||
'QTFrame:pc:ADDR'
|
||
Like 'QTFrame:N', but select the first tracepoint frame after the
|
||
currently selected frame whose PC is ADDR; ADDR is a hexadecimal
|
||
number.
|
||
|
||
'QTFrame:tdp:T'
|
||
Like 'QTFrame:N', but select the first tracepoint frame after the
|
||
currently selected frame that is a hit of tracepoint T; T is a
|
||
hexadecimal number.
|
||
|
||
'QTFrame:range:START:END'
|
||
Like 'QTFrame:N', but select the first tracepoint frame after the
|
||
currently selected frame whose PC is between START (inclusive) and
|
||
END (inclusive); START and END are hexadecimal numbers.
|
||
|
||
'QTFrame:outside:START:END'
|
||
Like 'QTFrame:range:START:END', but select the first frame
|
||
_outside_ the given range of addresses (exclusive).
|
||
|
||
'qTMinFTPILen'
|
||
This packet requests the minimum length of instruction at which a
|
||
fast tracepoint (*note Set Tracepoints::) may be placed. For
|
||
instance, on the 32-bit x86 architecture, it is possible to use a
|
||
4-byte jump, but it depends on the target system being able to
|
||
create trampolines in the first 64K of memory, which might or might
|
||
not be possible for that system. So the reply to this packet will
|
||
be 4 if it is able to arrange for that.
|
||
|
||
Replies:
|
||
|
||
'0'
|
||
The minimum instruction length is currently unknown.
|
||
'LENGTH'
|
||
The minimum instruction length is LENGTH, where LENGTH is a
|
||
hexadecimal number greater or equal to 1. A reply of 1 means
|
||
that a fast tracepoint may be placed on any instruction
|
||
regardless of size.
|
||
'E'
|
||
An error has occurred.
|
||
''
|
||
An empty reply indicates that the request is not supported by
|
||
the stub.
|
||
|
||
'QTStart'
|
||
Begin the tracepoint experiment. Begin collecting data from
|
||
tracepoint hits in the trace frame buffer. This packet supports
|
||
the 'qRelocInsn' reply (*note Relocate instruction reply packet:
|
||
Tracepoint Packets.).
|
||
|
||
'QTStop'
|
||
End the tracepoint experiment. Stop collecting trace frames.
|
||
|
||
'QTEnable:N:ADDR'
|
||
Enable tracepoint N at address ADDR in a started tracepoint
|
||
experiment. If the tracepoint was previously disabled, then
|
||
collection of data from it will resume.
|
||
|
||
'QTDisable:N:ADDR'
|
||
Disable tracepoint N at address ADDR in a started tracepoint
|
||
experiment. No more data will be collected from the tracepoint
|
||
unless 'QTEnable:N:ADDR' is subsequently issued.
|
||
|
||
'QTinit'
|
||
Clear the table of tracepoints, and empty the trace frame buffer.
|
||
|
||
'QTro:START1,END1:START2,END2:...'
|
||
Establish the given ranges of memory as "transparent". The stub
|
||
will answer requests for these ranges from memory's current
|
||
contents, if they were not collected as part of the tracepoint hit.
|
||
|
||
GDB uses this to mark read-only regions of memory, like those
|
||
containing program code. Since these areas never change, they
|
||
should still have the same contents they did when the tracepoint
|
||
was hit, so there's no reason for the stub to refuse to provide
|
||
their contents.
|
||
|
||
'QTDisconnected:VALUE'
|
||
Set the choice to what to do with the tracing run when GDB
|
||
disconnects from the target. A VALUE of 1 directs the target to
|
||
continue the tracing run, while 0 tells the target to stop tracing
|
||
if GDB is no longer in the picture.
|
||
|
||
'qTStatus'
|
||
Ask the stub if there is a trace experiment running right now.
|
||
|
||
The reply has the form:
|
||
|
||
'TRUNNING[;FIELD]...'
|
||
RUNNING is a single digit '1' if the trace is presently
|
||
running, or '0' if not. It is followed by semicolon-separated
|
||
optional fields that an agent may use to report additional
|
||
status.
|
||
|
||
If the trace is not running, the agent may report any of several
|
||
explanations as one of the optional fields:
|
||
|
||
'tnotrun:0'
|
||
No trace has been run yet.
|
||
|
||
'tstop[:TEXT]:0'
|
||
The trace was stopped by a user-originated stop command. The
|
||
optional TEXT field is a user-supplied string supplied as part
|
||
of the stop command (for instance, an explanation of why the
|
||
trace was stopped manually). It is hex-encoded.
|
||
|
||
'tfull:0'
|
||
The trace stopped because the trace buffer filled up.
|
||
|
||
'tdisconnected:0'
|
||
The trace stopped because GDB disconnected from the target.
|
||
|
||
'tpasscount:TPNUM'
|
||
The trace stopped because tracepoint TPNUM exceeded its pass
|
||
count.
|
||
|
||
'terror:TEXT:TPNUM'
|
||
The trace stopped because tracepoint TPNUM had an error. The
|
||
string TEXT is available to describe the nature of the error
|
||
(for instance, a divide by zero in the condition expression);
|
||
it is hex encoded.
|
||
|
||
'tunknown:0'
|
||
The trace stopped for some other reason.
|
||
|
||
Additional optional fields supply statistical and other
|
||
information. Although not required, they are extremely useful for
|
||
users monitoring the progress of a trace run. If a trace has
|
||
stopped, and these numbers are reported, they must reflect the
|
||
state of the just-stopped trace.
|
||
|
||
'tframes:N'
|
||
The number of trace frames in the buffer.
|
||
|
||
'tcreated:N'
|
||
The total number of trace frames created during the run. This
|
||
may be larger than the trace frame count, if the buffer is
|
||
circular.
|
||
|
||
'tsize:N'
|
||
The total size of the trace buffer, in bytes.
|
||
|
||
'tfree:N'
|
||
The number of bytes still unused in the buffer.
|
||
|
||
'circular:N'
|
||
The value of the circular trace buffer flag. '1' means that
|
||
the trace buffer is circular and old trace frames will be
|
||
discarded if necessary to make room, '0' means that the trace
|
||
buffer is linear and may fill up.
|
||
|
||
'disconn:N'
|
||
The value of the disconnected tracing flag. '1' means that
|
||
tracing will continue after GDB disconnects, '0' means that
|
||
the trace run will stop.
|
||
|
||
'qTP:TP:ADDR'
|
||
Ask the stub for the current state of tracepoint number TP at
|
||
address ADDR.
|
||
|
||
Replies:
|
||
'VHITS:USAGE'
|
||
The tracepoint has been hit HITS times so far during the trace
|
||
run, and accounts for USAGE in the trace buffer. Note that
|
||
'while-stepping' steps are not counted as separate hits, but
|
||
the steps' space consumption is added into the usage number.
|
||
|
||
'qTV:VAR'
|
||
Ask the stub for the value of the trace state variable number VAR.
|
||
|
||
Replies:
|
||
'VVALUE'
|
||
The value of the variable is VALUE. This will be the current
|
||
value of the variable if the user is examining a running
|
||
target, or a saved value if the variable was collected in the
|
||
trace frame that the user is looking at. Note that multiple
|
||
requests may result in different reply values, such as when
|
||
requesting values while the program is running.
|
||
|
||
'U'
|
||
The value of the variable is unknown. This would occur, for
|
||
example, if the user is examining a trace frame in which the
|
||
requested variable was not collected.
|
||
|
||
'qTfP'
|
||
'qTsP'
|
||
These packets request data about tracepoints that are being used by
|
||
the target. GDB sends 'qTfP' to get the first piece of data, and
|
||
multiple 'qTsP' to get additional pieces. Replies to these packets
|
||
generally take the form of the 'QTDP' packets that define
|
||
tracepoints. (FIXME add detailed syntax)
|
||
|
||
'qTfV'
|
||
'qTsV'
|
||
These packets request data about trace state variables that are on
|
||
the target. GDB sends 'qTfV' to get the first vari of data, and
|
||
multiple 'qTsV' to get additional variables. Replies to these
|
||
packets follow the syntax of the 'QTDV' packets that define trace
|
||
state variables.
|
||
|
||
'qTfSTM'
|
||
'qTsSTM'
|
||
These packets request data about static tracepoint markers that
|
||
exist in the target program. GDB sends 'qTfSTM' to get the first
|
||
piece of data, and multiple 'qTsSTM' to get additional pieces.
|
||
Replies to these packets take the following form:
|
||
|
||
Reply:
|
||
'm ADDRESS:ID:EXTRA'
|
||
A single marker
|
||
'm ADDRESS:ID:EXTRA,ADDRESS:ID:EXTRA...'
|
||
a comma-separated list of markers
|
||
'l'
|
||
(lower case letter 'L') denotes end of list.
|
||
'E NN'
|
||
An error occurred. The error number NN is given as hex
|
||
digits.
|
||
''
|
||
An empty reply indicates that the request is not supported by
|
||
the stub.
|
||
|
||
The ADDRESS is encoded in hex; ID and EXTRA are strings encoded in
|
||
hex.
|
||
|
||
In response to each query, the target will reply with a list of one
|
||
or more markers, separated by commas. GDB will respond to each
|
||
reply with a request for more markers (using the 'qs' form of the
|
||
query), until the target responds with 'l' (lower-case ell, for
|
||
"last").
|
||
|
||
'qTSTMat:ADDRESS'
|
||
This packets requests data about static tracepoint markers in the
|
||
target program at ADDRESS. Replies to this packet follow the
|
||
syntax of the 'qTfSTM' and 'qTsSTM' packets that list static
|
||
tracepoint markers.
|
||
|
||
'QTSave:FILENAME'
|
||
This packet directs the target to save trace data to the file name
|
||
FILENAME in the target's filesystem. The FILENAME is encoded as a
|
||
hex string; the interpretation of the file name (relative vs
|
||
absolute, wild cards, etc) is up to the target.
|
||
|
||
'qTBuffer:OFFSET,LEN'
|
||
Return up to LEN bytes of the current contents of trace buffer,
|
||
starting at OFFSET. The trace buffer is treated as if it were a
|
||
contiguous collection of traceframes, as per the trace file format.
|
||
The reply consists as many hex-encoded bytes as the target can
|
||
deliver in a packet; it is not an error to return fewer than were
|
||
asked for. A reply consisting of just 'l' indicates that no bytes
|
||
are available.
|
||
|
||
'QTBuffer:circular:VALUE'
|
||
This packet directs the target to use a circular trace buffer if
|
||
VALUE is 1, or a linear buffer if the value is 0.
|
||
|
||
'QTBuffer:size:SIZE'
|
||
This packet directs the target to make the trace buffer be of size
|
||
SIZE if possible. A value of '-1' tells the target to use whatever
|
||
size it prefers.
|
||
|
||
'QTNotes:[TYPE:TEXT][;TYPE:TEXT]...'
|
||
This packet adds optional textual notes to the trace run.
|
||
Allowable types include 'user', 'notes', and 'tstop', the TEXT
|
||
fields are arbitrary strings, hex-encoded.
|
||
|
||
E.6.1 Relocate instruction reply packet
|
||
---------------------------------------
|
||
|
||
When installing fast tracepoints in memory, the target may need to
|
||
relocate the instruction currently at the tracepoint address to a
|
||
different address in memory. For most instructions, a simple copy is
|
||
enough, but, for example, call instructions that implicitly push the
|
||
return address on the stack, and relative branches or other PC-relative
|
||
instructions require offset adjustment, so that the effect of executing
|
||
the instruction at a different address is the same as if it had executed
|
||
in the original location.
|
||
|
||
In response to several of the tracepoint packets, the target may also
|
||
respond with a number of intermediate 'qRelocInsn' request packets
|
||
before the final result packet, to have GDB handle this relocation
|
||
operation. If a packet supports this mechanism, its documentation will
|
||
explicitly say so. See for example the above descriptions for the
|
||
'QTStart' and 'QTDP' packets. The format of the request is:
|
||
|
||
'qRelocInsn:FROM;TO'
|
||
|
||
This requests GDB to copy instruction at address FROM to address
|
||
TO, possibly adjusted so that executing the instruction at TO has
|
||
the same effect as executing it at FROM. GDB writes the adjusted
|
||
instruction to target memory starting at TO.
|
||
|
||
Replies:
|
||
'qRelocInsn:ADJUSTED_SIZE'
|
||
Informs the stub the relocation is complete. The ADJUSTED_SIZE is
|
||
the length in bytes of resulting relocated instruction sequence.
|
||
'E NN'
|
||
A badly formed request was detected, or an error was encountered
|
||
while relocating the instruction.
|
||
|
||
|
||
File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol
|
||
|
||
E.7 Host I/O Packets
|
||
====================
|
||
|
||
The "Host I/O" packets allow GDB to perform I/O operations on the far
|
||
side of a remote link. For example, Host I/O is used to upload and
|
||
download files to a remote target with its own filesystem. Host I/O
|
||
uses the same constant values and data structure layout as the
|
||
target-initiated File-I/O protocol. However, the Host I/O packets are
|
||
structured differently. The target-initiated protocol relies on target
|
||
memory to store parameters and buffers. Host I/O requests are initiated
|
||
by GDB, and the target's memory is not involved. *Note File-I/O Remote
|
||
Protocol Extension::, for more details on the target-initiated protocol.
|
||
|
||
The Host I/O request packets all encode a single operation along with
|
||
its arguments. They have this format:
|
||
|
||
'vFile:OPERATION: PARAMETER...'
|
||
OPERATION is the name of the particular request; the target should
|
||
compare the entire packet name up to the second colon when checking
|
||
for a supported operation. The format of PARAMETER depends on the
|
||
operation. Numbers are always passed in hexadecimal. Negative
|
||
numbers have an explicit minus sign (i.e. two's complement is not
|
||
used). Strings (e.g. filenames) are encoded as a series of
|
||
hexadecimal bytes. The last argument to a system call may be a
|
||
buffer of escaped binary data (*note Binary Data::).
|
||
|
||
The valid responses to Host I/O packets are:
|
||
|
||
'F RESULT [, ERRNO] [; ATTACHMENT]'
|
||
RESULT is the integer value returned by this operation, usually
|
||
non-negative for success and -1 for errors. If an error has
|
||
occured, ERRNO will be included in the result specifying a value
|
||
defined by the File-I/O protocol (*note Errno Values::). For
|
||
operations which return data, ATTACHMENT supplies the data as a
|
||
binary buffer. Binary buffers in response packets are escaped in
|
||
the normal way (*note Binary Data::). See the individual packet
|
||
documentation for the interpretation of RESULT and ATTACHMENT.
|
||
|
||
''
|
||
An empty response indicates that this operation is not recognized.
|
||
|
||
These are the supported Host I/O operations:
|
||
|
||
'vFile:open: FILENAME, FLAGS, MODE'
|
||
Open a file at FILENAME and return a file descriptor for it, or
|
||
return -1 if an error occurs. The FILENAME is a string, FLAGS is
|
||
an integer indicating a mask of open flags (*note Open Flags::),
|
||
and MODE is an integer indicating a mask of mode bits to use if the
|
||
file is created (*note mode_t Values::). *Note open::, for details
|
||
of the open flags and mode values.
|
||
|
||
'vFile:close: FD'
|
||
Close the open file corresponding to FD and return 0, or -1 if an
|
||
error occurs.
|
||
|
||
'vFile:pread: FD, COUNT, OFFSET'
|
||
Read data from the open file corresponding to FD. Up to COUNT
|
||
bytes will be read from the file, starting at OFFSET relative to
|
||
the start of the file. The target may read fewer bytes; common
|
||
reasons include packet size limits and an end-of-file condition.
|
||
The number of bytes read is returned. Zero should only be returned
|
||
for a successful read at the end of the file, or if COUNT was zero.
|
||
|
||
The data read should be returned as a binary attachment on success.
|
||
If zero bytes were read, the response should include an empty
|
||
binary attachment (i.e. a trailing semicolon). The return value is
|
||
the number of target bytes read; the binary attachment may be
|
||
longer if some characters were escaped.
|
||
|
||
'vFile:pwrite: FD, OFFSET, DATA'
|
||
Write DATA (a binary buffer) to the open file corresponding to FD.
|
||
Start the write at OFFSET from the start of the file. Unlike many
|
||
'write' system calls, there is no separate COUNT argument; the
|
||
length of DATA in the packet is used. 'vFile:pwrite' returns the
|
||
number of bytes written, which may be shorter than the length of
|
||
DATA, or -1 if an error occurred.
|
||
|
||
'vFile:fstat: FD'
|
||
Get information about the open file corresponding to FD. On
|
||
success the information is returned as a binary attachment and the
|
||
return value is the size of this attachment in bytes. If an error
|
||
occurs the return value is -1. The format of the returned binary
|
||
attachment is as described in *note struct stat::.
|
||
|
||
'vFile:unlink: FILENAME'
|
||
Delete the file at FILENAME on the target. Return 0, or -1 if an
|
||
error occurs. The FILENAME is a string.
|
||
|
||
'vFile:readlink: FILENAME'
|
||
Read value of symbolic link FILENAME on the target. Return the
|
||
number of bytes read, or -1 if an error occurs.
|
||
|
||
The data read should be returned as a binary attachment on success.
|
||
If zero bytes were read, the response should include an empty
|
||
binary attachment (i.e. a trailing semicolon). The return value is
|
||
the number of target bytes read; the binary attachment may be
|
||
longer if some characters were escaped.
|
||
|
||
'vFile:setfs: PID'
|
||
Select the filesystem on which 'vFile' operations with FILENAME
|
||
arguments will operate. This is required for GDB to be able to
|
||
access files on remote targets where the remote stub does not share
|
||
a common filesystem with the inferior(s).
|
||
|
||
If PID is nonzero, select the filesystem as seen by process PID.
|
||
If PID is zero, select the filesystem as seen by the remote stub.
|
||
Return 0 on success, or -1 if an error occurs. If 'vFile:setfs:'
|
||
indicates success, the selected filesystem remains selected until
|
||
the next successful 'vFile:setfs:' operation.
|
||
|
||
|
||
File: gdb.info, Node: Interrupts, Next: Notification Packets, Prev: Host I/O Packets, Up: Remote Protocol
|
||
|
||
E.8 Interrupts
|
||
==============
|
||
|
||
In all-stop mode, when a program on the remote target is running, GDB
|
||
may attempt to interrupt it by sending a 'Ctrl-C', 'BREAK' or a 'BREAK'
|
||
followed by 'g', control of which is specified via GDB's
|
||
'interrupt-sequence'.
|
||
|
||
The precise meaning of 'BREAK' is defined by the transport mechanism
|
||
and may, in fact, be undefined. GDB does not currently define a 'BREAK'
|
||
mechanism for any of the network interfaces except for TCP, in which
|
||
case GDB sends the 'telnet' BREAK sequence.
|
||
|
||
'Ctrl-C', on the other hand, is defined and implemented for all
|
||
transport mechanisms. It is represented by sending the single byte
|
||
'0x03' without any of the usual packet overhead described in the
|
||
Overview section (*note Overview::). When a '0x03' byte is transmitted
|
||
as part of a packet, it is considered to be packet data and does _not_
|
||
represent an interrupt. E.g., an 'X' packet (*note X packet::), used
|
||
for binary downloads, may include an unescaped '0x03' as part of its
|
||
packet.
|
||
|
||
'BREAK' followed by 'g' is also known as Magic SysRq g. When Linux
|
||
kernel receives this sequence from serial port, it stops execution and
|
||
connects to gdb.
|
||
|
||
In non-stop mode, because packet resumptions are asynchronous (*note
|
||
vCont packet::), GDB is always free to send a remote command to the
|
||
remote stub, even when the target is running. For that reason, GDB
|
||
instead sends a regular packet (*note vCtrlC packet::) with the usual
|
||
packet framing instead of the single byte '0x03'.
|
||
|
||
Stubs are not required to recognize these interrupt mechanisms and
|
||
the precise meaning associated with receipt of the interrupt is
|
||
implementation defined. If the target supports debugging of multiple
|
||
threads and/or processes, it should attempt to interrupt all
|
||
currently-executing threads and processes. If the stub is successful at
|
||
interrupting the running program, it should send one of the stop reply
|
||
packets (*note Stop Reply Packets::) to GDB as a result of successfully
|
||
stopping the program in all-stop mode, and a stop reply for each stopped
|
||
thread in non-stop mode. Interrupts received while the program is
|
||
stopped are queued and the program will be interrupted when it is
|
||
resumed next time.
|
||
|
||
|
||
File: gdb.info, Node: Notification Packets, Next: Remote Non-Stop, Prev: Interrupts, Up: Remote Protocol
|
||
|
||
E.9 Notification Packets
|
||
========================
|
||
|
||
The GDB remote serial protocol includes "notifications", packets that
|
||
require no acknowledgment. Both the GDB and the stub may send
|
||
notifications (although the only notifications defined at present are
|
||
sent by the stub). Notifications carry information without incurring
|
||
the round-trip latency of an acknowledgment, and so are useful for
|
||
low-impact communications where occasional packet loss is not a problem.
|
||
|
||
A notification packet has the form '% DATA # CHECKSUM', where DATA is
|
||
the content of the notification, and CHECKSUM is a checksum of DATA,
|
||
computed and formatted as for ordinary GDB packets. A notification's
|
||
DATA never contains '$', '%' or '#' characters. Upon receiving a
|
||
notification, the recipient sends no '+' or '-' to acknowledge the
|
||
notification's receipt or to report its corruption.
|
||
|
||
Every notification's DATA begins with a name, which contains no colon
|
||
characters, followed by a colon character.
|
||
|
||
Recipients should silently ignore corrupted notifications and
|
||
notifications they do not understand. Recipients should restart timeout
|
||
periods on receipt of a well-formed notification, whether or not they
|
||
understand it.
|
||
|
||
Senders should only send the notifications described here when this
|
||
protocol description specifies that they are permitted. In the future,
|
||
we may extend the protocol to permit existing notifications in new
|
||
contexts; this rule helps older senders avoid confusing newer
|
||
recipients.
|
||
|
||
(Older versions of GDB ignore bytes received until they see the '$'
|
||
byte that begins an ordinary packet, so new stubs may transmit
|
||
notifications without fear of confusing older clients. There are no
|
||
notifications defined for GDB to send at the moment, but we assume that
|
||
most older stubs would ignore them, as well.)
|
||
|
||
Each notification is comprised of three parts:
|
||
'NAME:EVENT'
|
||
The notification packet is sent by the side that initiates the
|
||
exchange (currently, only the stub does that), with EVENT carrying
|
||
the specific information about the notification, and NAME
|
||
specifying the name of the notification.
|
||
'ACK'
|
||
The acknowledge sent by the other side, usually GDB, to acknowledge
|
||
the exchange and request the event.
|
||
|
||
The purpose of an asynchronous notification mechanism is to report to
|
||
GDB that something interesting happened in the remote stub.
|
||
|
||
The remote stub may send notification NAME:EVENT at any time, but GDB
|
||
acknowledges the notification when appropriate. The notification event
|
||
is pending before GDB acknowledges. Only one notification at a time may
|
||
be pending; if additional events occur before GDB has acknowledged the
|
||
previous notification, they must be queued by the stub for later
|
||
synchronous transmission in response to ACK packets from GDB. Because
|
||
the notification mechanism is unreliable, the stub is permitted to
|
||
resend a notification if it believes GDB may not have received it.
|
||
|
||
Specifically, notifications may appear when GDB is not otherwise
|
||
reading input from the stub, or when GDB is expecting to read a normal
|
||
synchronous response or a '+'/'-' acknowledgment to a packet it has
|
||
sent. Notification packets are distinct from any other communication
|
||
from the stub so there is no ambiguity.
|
||
|
||
After receiving a notification, GDB shall acknowledge it by sending a
|
||
ACK packet as a regular, synchronous request to the stub. Such
|
||
acknowledgment is not required to happen immediately, as GDB is
|
||
permitted to send other, unrelated packets to the stub first, which the
|
||
stub should process normally.
|
||
|
||
Upon receiving a ACK packet, if the stub has other queued events to
|
||
report to GDB, it shall respond by sending a normal EVENT. GDB shall
|
||
then send another ACK packet to solicit further responses; again, it is
|
||
permitted to send other, unrelated packets as well which the stub should
|
||
process normally.
|
||
|
||
If the stub receives a ACK packet and there are no additional EVENT
|
||
to report, the stub shall return an 'OK' response. At this point, GDB
|
||
has finished processing a notification and the stub has completed
|
||
sending any queued events. GDB won't accept any new notifications until
|
||
the final 'OK' is received . If further notification events occur, the
|
||
stub shall send a new notification, GDB shall accept the notification,
|
||
and the process shall be repeated.
|
||
|
||
The process of asynchronous notification can be illustrated by the
|
||
following example:
|
||
<- %Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;
|
||
...
|
||
-> vStopped
|
||
<- T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;
|
||
-> vStopped
|
||
<- T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;
|
||
-> vStopped
|
||
<- OK
|
||
|
||
The following notifications are defined:
|
||
|
||
NotificationAck Event Description
|
||
|
||
Stop vStopped REPLY. The REPLY has the Report an asynchronous
|
||
form of a stop reply, as stop event in non-stop
|
||
described in mode.
|
||
*note Stop Reply Packets::.
|
||
Refer to
|
||
*note Remote Non-Stop::,
|
||
for information on how
|
||
these notifications are
|
||
acknowledged by GDB.
|
||
|
||
|
||
File: gdb.info, Node: Remote Non-Stop, Next: Packet Acknowledgment, Prev: Notification Packets, Up: Remote Protocol
|
||
|
||
E.10 Remote Protocol Support for Non-Stop Mode
|
||
==============================================
|
||
|
||
GDB's remote protocol supports non-stop debugging of multi-threaded
|
||
programs, as described in *note Non-Stop Mode::. If the stub supports
|
||
non-stop mode, it should report that to GDB by including 'QNonStop+' in
|
||
its 'qSupported' response (*note qSupported::).
|
||
|
||
GDB typically sends a 'QNonStop' packet only when establishing a new
|
||
connection with the stub. Entering non-stop mode does not alter the
|
||
state of any currently-running threads, but targets must stop all
|
||
threads in any already-attached processes when entering all-stop mode.
|
||
GDB uses the '?' packet as necessary to probe the target state after a
|
||
mode change.
|
||
|
||
In non-stop mode, when an attached process encounters an event that
|
||
would otherwise be reported with a stop reply, it uses the asynchronous
|
||
notification mechanism (*note Notification Packets::) to inform GDB. In
|
||
contrast to all-stop mode, where all threads in all processes are
|
||
stopped when a stop reply is sent, in non-stop mode only the thread
|
||
reporting the stop event is stopped. That is, when reporting a 'S' or
|
||
'T' response to indicate completion of a step operation, hitting a
|
||
breakpoint, or a fault, only the affected thread is stopped; any other
|
||
still-running threads continue to run. When reporting a 'W' or 'X'
|
||
response, all running threads belonging to other attached processes
|
||
continue to run.
|
||
|
||
In non-stop mode, the target shall respond to the '?' packet as
|
||
follows. First, any incomplete stop reply notification/'vStopped'
|
||
sequence in progress is abandoned. The target must begin a new sequence
|
||
reporting stop events for all stopped threads, whether or not it has
|
||
previously reported those events to GDB. The first stop reply is sent
|
||
as a synchronous reply to the '?' packet, and subsequent stop replies
|
||
are sent as responses to 'vStopped' packets using the mechanism
|
||
described above. The target must not send asynchronous stop reply
|
||
notifications until the sequence is complete. If all threads are
|
||
running when the target receives the '?' packet, or if the target is not
|
||
attached to any process, it shall respond 'OK'.
|
||
|
||
If the stub supports non-stop mode, it should also support the
|
||
'swbreak' stop reason if software breakpoints are supported, and the
|
||
'hwbreak' stop reason if hardware breakpoints are supported (*note
|
||
swbreak stop reason::). This is because given the asynchronous nature
|
||
of non-stop mode, between the time a thread hits a breakpoint and the
|
||
time the event is finally processed by GDB, the breakpoint may have
|
||
already been removed from the target. Due to this, GDB needs to be able
|
||
to tell whether a trap stop was caused by a delayed breakpoint event,
|
||
which should be ignored, as opposed to a random trap signal, which
|
||
should be reported to the user. Note the 'swbreak' feature implies that
|
||
the target is responsible for adjusting the PC when a software
|
||
breakpoint triggers, if necessary, such as on the x86 architecture.
|
||
|
||
|
||
File: gdb.info, Node: Packet Acknowledgment, Next: Examples, Prev: Remote Non-Stop, Up: Remote Protocol
|
||
|
||
E.11 Packet Acknowledgment
|
||
==========================
|
||
|
||
By default, when either the host or the target machine receives a
|
||
packet, the first response expected is an acknowledgment: either '+' (to
|
||
indicate the package was received correctly) or '-' (to request
|
||
retransmission). This mechanism allows the GDB remote protocol to
|
||
operate over unreliable transport mechanisms, such as a serial line.
|
||
|
||
In cases where the transport mechanism is itself reliable (such as a
|
||
pipe or TCP connection), the '+'/'-' acknowledgments are redundant. It
|
||
may be desirable to disable them in that case to reduce communication
|
||
overhead, or for other reasons. This can be accomplished by means of
|
||
the 'QStartNoAckMode' packet; *note QStartNoAckMode::.
|
||
|
||
When in no-acknowledgment mode, neither the stub nor GDB shall send
|
||
or expect '+'/'-' protocol acknowledgments. The packet and response
|
||
format still includes the normal checksum, as described in *note
|
||
Overview::, but the checksum may be ignored by the receiver.
|
||
|
||
If the stub supports 'QStartNoAckMode' and prefers to operate in
|
||
no-acknowledgment mode, it should report that to GDB by including
|
||
'QStartNoAckMode+' in its response to 'qSupported'; *note qSupported::.
|
||
If GDB also supports 'QStartNoAckMode' and it has not been disabled via
|
||
the 'set remote noack-packet off' command (*note Remote
|
||
Configuration::), GDB may then send a 'QStartNoAckMode' packet to the
|
||
stub. Only then may the stub actually turn off packet acknowledgments.
|
||
GDB sends a final '+' acknowledgment of the stub's 'OK' response, which
|
||
can be safely ignored by the stub.
|
||
|
||
Note that 'set remote noack-packet' command only affects negotiation
|
||
between GDB and the stub when subsequent connections are made; it does
|
||
not affect the protocol acknowledgment state for any current connection.
|
||
Since '+'/'-' acknowledgments are enabled by default when a new
|
||
connection is established, there is also no protocol request to
|
||
re-enable the acknowledgments for the current connection, once disabled.
|
||
|
||
|
||
File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Packet Acknowledgment, Up: Remote Protocol
|
||
|
||
E.12 Examples
|
||
=============
|
||
|
||
Example sequence of a target being re-started. Notice how the restart
|
||
does not get any direct output:
|
||
|
||
-> R00
|
||
<- +
|
||
_target restarts_
|
||
-> ?
|
||
<- +
|
||
<- T001:1234123412341234
|
||
-> +
|
||
|
||
Example sequence of a target being stepped by a single instruction:
|
||
|
||
-> G1445...
|
||
<- +
|
||
-> s
|
||
<- +
|
||
_time passes_
|
||
<- T001:1234123412341234
|
||
-> +
|
||
-> g
|
||
<- +
|
||
<- 1455...
|
||
-> +
|
||
|
||
|
||
File: gdb.info, Node: File-I/O Remote Protocol Extension, Next: Library List Format, Prev: Examples, Up: Remote Protocol
|
||
|
||
E.13 File-I/O Remote Protocol Extension
|
||
=======================================
|
||
|
||
* Menu:
|
||
|
||
* File-I/O Overview::
|
||
* Protocol Basics::
|
||
* The F Request Packet::
|
||
* The F Reply Packet::
|
||
* The Ctrl-C Message::
|
||
* Console I/O::
|
||
* List of Supported Calls::
|
||
* Protocol-specific Representation of Datatypes::
|
||
* Constants::
|
||
* File-I/O Examples::
|
||
|
||
|
||
File: gdb.info, Node: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension
|
||
|
||
E.13.1 File-I/O Overview
|
||
------------------------
|
||
|
||
The "File I/O remote protocol extension" (short: File-I/O) allows the
|
||
target to use the host's file system and console I/O to perform various
|
||
system calls. System calls on the target system are translated into a
|
||
remote protocol packet to the host system, which then performs the
|
||
needed actions and returns a response packet to the target system. This
|
||
simulates file system operations even on targets that lack file systems.
|
||
|
||
The protocol is defined to be independent of both the host and target
|
||
systems. It uses its own internal representation of datatypes and
|
||
values. Both GDB and the target's GDB stub are responsible for
|
||
translating the system-dependent value representations into the internal
|
||
protocol representations when data is transmitted.
|
||
|
||
The communication is synchronous. A system call is possible only
|
||
when GDB is waiting for a response from the 'C', 'c', 'S' or 's'
|
||
packets. While GDB handles the request for a system call, the target is
|
||
stopped to allow deterministic access to the target's memory. Therefore
|
||
File-I/O is not interruptible by target signals. On the other hand, it
|
||
is possible to interrupt File-I/O by a user interrupt ('Ctrl-C') within
|
||
GDB.
|
||
|
||
The target's request to perform a host system call does not finish
|
||
the latest 'C', 'c', 'S' or 's' action. That means, after finishing the
|
||
system call, the target returns to continuing the previous activity
|
||
(continue, step). No additional continue or step request from GDB is
|
||
required.
|
||
|
||
(gdb) continue
|
||
<- target requests 'system call X'
|
||
target is stopped, GDB executes system call
|
||
-> GDB returns result
|
||
... target continues, GDB returns to wait for the target
|
||
<- target hits breakpoint and sends a Txx packet
|
||
|
||
The protocol only supports I/O on the console and to regular files on
|
||
the host file system. Character or block special devices, pipes, named
|
||
pipes, sockets or any other communication method on the host system are
|
||
not supported by this protocol.
|
||
|
||
File I/O is not supported in non-stop mode.
|
||
|
||
|
||
File: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension
|
||
|
||
E.13.2 Protocol Basics
|
||
----------------------
|
||
|
||
The File-I/O protocol uses the 'F' packet as the request as well as
|
||
reply packet. Since a File-I/O system call can only occur when GDB is
|
||
waiting for a response from the continuing or stepping target, the
|
||
File-I/O request is a reply that GDB has to expect as a result of a
|
||
previous 'C', 'c', 'S' or 's' packet. This 'F' packet contains all
|
||
information needed to allow GDB to call the appropriate host system
|
||
call:
|
||
|
||
* A unique identifier for the requested system call.
|
||
|
||
* All parameters to the system call. Pointers are given as addresses
|
||
in the target memory address space. Pointers to strings are given
|
||
as pointer/length pair. Numerical values are given as they are.
|
||
Numerical control flags are given in a protocol-specific
|
||
representation.
|
||
|
||
At this point, GDB has to perform the following actions.
|
||
|
||
* If the parameters include pointer values to data needed as input to
|
||
a system call, GDB requests this data from the target with a
|
||
standard 'm' packet request. This additional communication has to
|
||
be expected by the target implementation and is handled as any
|
||
other 'm' packet.
|
||
|
||
* GDB translates all value from protocol representation to host
|
||
representation as needed. Datatypes are coerced into the host
|
||
types.
|
||
|
||
* GDB calls the system call.
|
||
|
||
* It then coerces datatypes back to protocol representation.
|
||
|
||
* If the system call is expected to return data in buffer space
|
||
specified by pointer parameters to the call, the data is
|
||
transmitted to the target using a 'M' or 'X' packet. This packet
|
||
has to be expected by the target implementation and is handled as
|
||
any other 'M' or 'X' packet.
|
||
|
||
Eventually GDB replies with another 'F' packet which contains all
|
||
necessary information for the target to continue. This at least
|
||
contains
|
||
|
||
* Return value.
|
||
|
||
* 'errno', if has been changed by the system call.
|
||
|
||
* "Ctrl-C" flag.
|
||
|
||
After having done the needed type and value coercion, the target
|
||
continues the latest continue or step action.
|
||
|
||
|
||
File: gdb.info, Node: The F Request Packet, Next: The F Reply Packet, Prev: Protocol Basics, Up: File-I/O Remote Protocol Extension
|
||
|
||
E.13.3 The 'F' Request Packet
|
||
-----------------------------
|
||
|
||
The 'F' request packet has the following format:
|
||
|
||
'FCALL-ID,PARAMETER...'
|
||
|
||
CALL-ID is the identifier to indicate the host system call to be
|
||
called. This is just the name of the function.
|
||
|
||
PARAMETER... are the parameters to the system call. Parameters are
|
||
hexadecimal integer values, either the actual values in case of
|
||
scalar datatypes, pointers to target buffer space in case of
|
||
compound datatypes and unspecified memory areas, or pointer/length
|
||
pairs in case of string parameters. These are appended to the
|
||
CALL-ID as a comma-delimited list. All values are transmitted in
|
||
ASCII string representation, pointer/length pairs separated by a
|
||
slash.
|
||
|
||
|
||
File: gdb.info, Node: The F Reply Packet, Next: The Ctrl-C Message, Prev: The F Request Packet, Up: File-I/O Remote Protocol Extension
|
||
|
||
E.13.4 The 'F' Reply Packet
|
||
---------------------------
|
||
|
||
The 'F' reply packet has the following format:
|
||
|
||
'FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT'
|
||
|
||
RETCODE is the return code of the system call as hexadecimal value.
|
||
|
||
ERRNO is the 'errno' set by the call, in protocol-specific
|
||
representation. This parameter can be omitted if the call was
|
||
successful.
|
||
|
||
CTRL-C FLAG is only sent if the user requested a break. In this
|
||
case, ERRNO must be sent as well, even if the call was successful.
|
||
The CTRL-C FLAG itself consists of the character 'C':
|
||
|
||
F0,0,C
|
||
|
||
or, if the call was interrupted before the host call has been
|
||
performed:
|
||
|
||
F-1,4,C
|
||
|
||
assuming 4 is the protocol-specific representation of 'EINTR'.
|
||
|
||
|
||
File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension
|
||
|
||
E.13.5 The 'Ctrl-C' Message
|
||
---------------------------
|
||
|
||
If the 'Ctrl-C' flag is set in the GDB reply packet (*note The F Reply
|
||
Packet::), the target should behave as if it had gotten a break message.
|
||
The meaning for the target is "system call interrupted by 'SIGINT'".
|
||
Consequentially, the target should actually stop (as with a break
|
||
message) and return to GDB with a 'T02' packet.
|
||
|
||
It's important for the target to know in which state the system call
|
||
was interrupted. There are two possible cases:
|
||
|
||
* The system call hasn't been performed on the host yet.
|
||
|
||
* The system call on the host has been finished.
|
||
|
||
These two states can be distinguished by the target by the value of
|
||
the returned 'errno'. If it's the protocol representation of 'EINTR',
|
||
the system call hasn't been performed. This is equivalent to the
|
||
'EINTR' handling on POSIX systems. In any other case, the target may
|
||
presume that the system call has been finished -- successfully or not --
|
||
and should behave as if the break message arrived right after the system
|
||
call.
|
||
|
||
GDB must behave reliably. If the system call has not been called
|
||
yet, GDB may send the 'F' reply immediately, setting 'EINTR' as 'errno'
|
||
in the packet. If the system call on the host has been finished before
|
||
the user requests a break, the full action must be finished by GDB.
|
||
This requires sending 'M' or 'X' packets as necessary. The 'F' packet
|
||
may only be sent when either nothing has happened or the full action has
|
||
been completed.
|
||
|
||
|
||
File: gdb.info, Node: Console I/O, Next: List of Supported Calls, Prev: The Ctrl-C Message, Up: File-I/O Remote Protocol Extension
|
||
|
||
E.13.6 Console I/O
|
||
------------------
|
||
|
||
By default and if not explicitly closed by the target system, the file
|
||
descriptors 0, 1 and 2 are connected to the GDB console. Output on the
|
||
GDB console is handled as any other file output operation ('write(1,
|
||
...)' or 'write(2, ...)'). Console input is handled by GDB so that
|
||
after the target read request from file descriptor 0 all following
|
||
typing is buffered until either one of the following conditions is met:
|
||
|
||
* The user types 'Ctrl-c'. The behaviour is as explained above, and
|
||
the 'read' system call is treated as finished.
|
||
|
||
* The user presses <RET>. This is treated as end of input with a
|
||
trailing newline.
|
||
|
||
* The user types 'Ctrl-d'. This is treated as end of input. No
|
||
trailing character (neither newline nor 'Ctrl-D') is appended to
|
||
the input.
|
||
|
||
If the user has typed more characters than fit in the buffer given to
|
||
the 'read' call, the trailing characters are buffered in GDB until
|
||
either another 'read(0, ...)' is requested by the target, or debugging
|
||
is stopped at the user's request.
|
||
|
||
|
||
File: gdb.info, Node: List of Supported Calls, Next: Protocol-specific Representation of Datatypes, Prev: Console I/O, Up: File-I/O Remote Protocol Extension
|
||
|
||
E.13.7 List of Supported Calls
|
||
------------------------------
|
||
|
||
* Menu:
|
||
|
||
* open::
|
||
* close::
|
||
* read::
|
||
* write::
|
||
* lseek::
|
||
* rename::
|
||
* unlink::
|
||
* stat/fstat::
|
||
* gettimeofday::
|
||
* isatty::
|
||
* system::
|
||
|
||
|
||
File: gdb.info, Node: open, Next: close, Up: List of Supported Calls
|
||
|
||
open
|
||
....
|
||
|
||
Synopsis:
|
||
int open(const char *pathname, int flags);
|
||
int open(const char *pathname, int flags, mode_t mode);
|
||
|
||
Request:
|
||
'Fopen,PATHPTR/LEN,FLAGS,MODE'
|
||
|
||
FLAGS is the bitwise 'OR' of the following values:
|
||
|
||
'O_CREAT'
|
||
If the file does not exist it will be created. The host rules
|
||
apply as far as file ownership and time stamps are concerned.
|
||
|
||
'O_EXCL'
|
||
When used with 'O_CREAT', if the file already exists it is an
|
||
error and open() fails.
|
||
|
||
'O_TRUNC'
|
||
If the file already exists and the open mode allows writing
|
||
('O_RDWR' or 'O_WRONLY' is given) it will be truncated to zero
|
||
length.
|
||
|
||
'O_APPEND'
|
||
The file is opened in append mode.
|
||
|
||
'O_RDONLY'
|
||
The file is opened for reading only.
|
||
|
||
'O_WRONLY'
|
||
The file is opened for writing only.
|
||
|
||
'O_RDWR'
|
||
The file is opened for reading and writing.
|
||
|
||
Other bits are silently ignored.
|
||
|
||
MODE is the bitwise 'OR' of the following values:
|
||
|
||
'S_IRUSR'
|
||
User has read permission.
|
||
|
||
'S_IWUSR'
|
||
User has write permission.
|
||
|
||
'S_IRGRP'
|
||
Group has read permission.
|
||
|
||
'S_IWGRP'
|
||
Group has write permission.
|
||
|
||
'S_IROTH'
|
||
Others have read permission.
|
||
|
||
'S_IWOTH'
|
||
Others have write permission.
|
||
|
||
Other bits are silently ignored.
|
||
|
||
Return value:
|
||
'open' returns the new file descriptor or -1 if an error occurred.
|
||
|
||
Errors:
|
||
|
||
'EEXIST'
|
||
PATHNAME already exists and 'O_CREAT' and 'O_EXCL' were used.
|
||
|
||
'EISDIR'
|
||
PATHNAME refers to a directory.
|
||
|
||
'EACCES'
|
||
The requested access is not allowed.
|
||
|
||
'ENAMETOOLONG'
|
||
PATHNAME was too long.
|
||
|
||
'ENOENT'
|
||
A directory component in PATHNAME does not exist.
|
||
|
||
'ENODEV'
|
||
PATHNAME refers to a device, pipe, named pipe or socket.
|
||
|
||
'EROFS'
|
||
PATHNAME refers to a file on a read-only filesystem and write
|
||
access was requested.
|
||
|
||
'EFAULT'
|
||
PATHNAME is an invalid pointer value.
|
||
|
||
'ENOSPC'
|
||
No space on device to create the file.
|
||
|
||
'EMFILE'
|
||
The process already has the maximum number of files open.
|
||
|
||
'ENFILE'
|
||
The limit on the total number of files open on the system has
|
||
been reached.
|
||
|
||
'EINTR'
|
||
The call was interrupted by the user.
|
||
|
||
|
||
File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls
|
||
|
||
close
|
||
.....
|
||
|
||
Synopsis:
|
||
int close(int fd);
|
||
|
||
Request:
|
||
'Fclose,FD'
|
||
|
||
Return value:
|
||
'close' returns zero on success, or -1 if an error occurred.
|
||
|
||
Errors:
|
||
|
||
'EBADF'
|
||
FD isn't a valid open file descriptor.
|
||
|
||
'EINTR'
|
||
The call was interrupted by the user.
|
||
|
||
|
||
File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls
|
||
|
||
read
|
||
....
|
||
|
||
Synopsis:
|
||
int read(int fd, void *buf, unsigned int count);
|
||
|
||
Request:
|
||
'Fread,FD,BUFPTR,COUNT'
|
||
|
||
Return value:
|
||
On success, the number of bytes read is returned. Zero indicates
|
||
end of file. If count is zero, read returns zero as well. On
|
||
error, -1 is returned.
|
||
|
||
Errors:
|
||
|
||
'EBADF'
|
||
FD is not a valid file descriptor or is not open for reading.
|
||
|
||
'EFAULT'
|
||
BUFPTR is an invalid pointer value.
|
||
|
||
'EINTR'
|
||
The call was interrupted by the user.
|
||
|
||
|
||
File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls
|
||
|
||
write
|
||
.....
|
||
|
||
Synopsis:
|
||
int write(int fd, const void *buf, unsigned int count);
|
||
|
||
Request:
|
||
'Fwrite,FD,BUFPTR,COUNT'
|
||
|
||
Return value:
|
||
On success, the number of bytes written are returned. Zero
|
||
indicates nothing was written. On error, -1 is returned.
|
||
|
||
Errors:
|
||
|
||
'EBADF'
|
||
FD is not a valid file descriptor or is not open for writing.
|
||
|
||
'EFAULT'
|
||
BUFPTR is an invalid pointer value.
|
||
|
||
'EFBIG'
|
||
An attempt was made to write a file that exceeds the
|
||
host-specific maximum file size allowed.
|
||
|
||
'ENOSPC'
|
||
No space on device to write the data.
|
||
|
||
'EINTR'
|
||
The call was interrupted by the user.
|
||
|
||
|
||
File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls
|
||
|
||
lseek
|
||
.....
|
||
|
||
Synopsis:
|
||
long lseek (int fd, long offset, int flag);
|
||
|
||
Request:
|
||
'Flseek,FD,OFFSET,FLAG'
|
||
|
||
FLAG is one of:
|
||
|
||
'SEEK_SET'
|
||
The offset is set to OFFSET bytes.
|
||
|
||
'SEEK_CUR'
|
||
The offset is set to its current location plus OFFSET bytes.
|
||
|
||
'SEEK_END'
|
||
The offset is set to the size of the file plus OFFSET bytes.
|
||
|
||
Return value:
|
||
On success, the resulting unsigned offset in bytes from the
|
||
beginning of the file is returned. Otherwise, a value of -1 is
|
||
returned.
|
||
|
||
Errors:
|
||
|
||
'EBADF'
|
||
FD is not a valid open file descriptor.
|
||
|
||
'ESPIPE'
|
||
FD is associated with the GDB console.
|
||
|
||
'EINVAL'
|
||
FLAG is not a proper value.
|
||
|
||
'EINTR'
|
||
The call was interrupted by the user.
|
||
|
||
|
||
File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls
|
||
|
||
rename
|
||
......
|
||
|
||
Synopsis:
|
||
int rename(const char *oldpath, const char *newpath);
|
||
|
||
Request:
|
||
'Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN'
|
||
|
||
Return value:
|
||
On success, zero is returned. On error, -1 is returned.
|
||
|
||
Errors:
|
||
|
||
'EISDIR'
|
||
NEWPATH is an existing directory, but OLDPATH is not a
|
||
directory.
|
||
|
||
'EEXIST'
|
||
NEWPATH is a non-empty directory.
|
||
|
||
'EBUSY'
|
||
OLDPATH or NEWPATH is a directory that is in use by some
|
||
process.
|
||
|
||
'EINVAL'
|
||
An attempt was made to make a directory a subdirectory of
|
||
itself.
|
||
|
||
'ENOTDIR'
|
||
A component used as a directory in OLDPATH or new path is not
|
||
a directory. Or OLDPATH is a directory and NEWPATH exists but
|
||
is not a directory.
|
||
|
||
'EFAULT'
|
||
OLDPATHPTR or NEWPATHPTR are invalid pointer values.
|
||
|
||
'EACCES'
|
||
No access to the file or the path of the file.
|
||
|
||
'ENAMETOOLONG'
|
||
|
||
OLDPATH or NEWPATH was too long.
|
||
|
||
'ENOENT'
|
||
A directory component in OLDPATH or NEWPATH does not exist.
|
||
|
||
'EROFS'
|
||
The file is on a read-only filesystem.
|
||
|
||
'ENOSPC'
|
||
The device containing the file has no room for the new
|
||
directory entry.
|
||
|
||
'EINTR'
|
||
The call was interrupted by the user.
|
||
|
||
|
||
File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls
|
||
|
||
unlink
|
||
......
|
||
|
||
Synopsis:
|
||
int unlink(const char *pathname);
|
||
|
||
Request:
|
||
'Funlink,PATHNAMEPTR/LEN'
|
||
|
||
Return value:
|
||
On success, zero is returned. On error, -1 is returned.
|
||
|
||
Errors:
|
||
|
||
'EACCES'
|
||
No access to the file or the path of the file.
|
||
|
||
'EPERM'
|
||
The system does not allow unlinking of directories.
|
||
|
||
'EBUSY'
|
||
The file PATHNAME cannot be unlinked because it's being used
|
||
by another process.
|
||
|
||
'EFAULT'
|
||
PATHNAMEPTR is an invalid pointer value.
|
||
|
||
'ENAMETOOLONG'
|
||
PATHNAME was too long.
|
||
|
||
'ENOENT'
|
||
A directory component in PATHNAME does not exist.
|
||
|
||
'ENOTDIR'
|
||
A component of the path is not a directory.
|
||
|
||
'EROFS'
|
||
The file is on a read-only filesystem.
|
||
|
||
'EINTR'
|
||
The call was interrupted by the user.
|
||
|
||
|
||
File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls
|
||
|
||
stat/fstat
|
||
..........
|
||
|
||
Synopsis:
|
||
int stat(const char *pathname, struct stat *buf);
|
||
int fstat(int fd, struct stat *buf);
|
||
|
||
Request:
|
||
'Fstat,PATHNAMEPTR/LEN,BUFPTR'
|
||
'Ffstat,FD,BUFPTR'
|
||
|
||
Return value:
|
||
On success, zero is returned. On error, -1 is returned.
|
||
|
||
Errors:
|
||
|
||
'EBADF'
|
||
FD is not a valid open file.
|
||
|
||
'ENOENT'
|
||
A directory component in PATHNAME does not exist or the path
|
||
is an empty string.
|
||
|
||
'ENOTDIR'
|
||
A component of the path is not a directory.
|
||
|
||
'EFAULT'
|
||
PATHNAMEPTR is an invalid pointer value.
|
||
|
||
'EACCES'
|
||
No access to the file or the path of the file.
|
||
|
||
'ENAMETOOLONG'
|
||
PATHNAME was too long.
|
||
|
||
'EINTR'
|
||
The call was interrupted by the user.
|
||
|
||
|
||
File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls
|
||
|
||
gettimeofday
|
||
............
|
||
|
||
Synopsis:
|
||
int gettimeofday(struct timeval *tv, void *tz);
|
||
|
||
Request:
|
||
'Fgettimeofday,TVPTR,TZPTR'
|
||
|
||
Return value:
|
||
On success, 0 is returned, -1 otherwise.
|
||
|
||
Errors:
|
||
|
||
'EINVAL'
|
||
TZ is a non-NULL pointer.
|
||
|
||
'EFAULT'
|
||
TVPTR and/or TZPTR is an invalid pointer value.
|
||
|
||
|
||
File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls
|
||
|
||
isatty
|
||
......
|
||
|
||
Synopsis:
|
||
int isatty(int fd);
|
||
|
||
Request:
|
||
'Fisatty,FD'
|
||
|
||
Return value:
|
||
Returns 1 if FD refers to the GDB console, 0 otherwise.
|
||
|
||
Errors:
|
||
|
||
'EINTR'
|
||
The call was interrupted by the user.
|
||
|
||
Note that the 'isatty' call is treated as a special case: it returns
|
||
1 to the target if the file descriptor is attached to the GDB console, 0
|
||
otherwise. Implementing through system calls would require implementing
|
||
'ioctl' and would be more complex than needed.
|
||
|
||
|
||
File: gdb.info, Node: system, Prev: isatty, Up: List of Supported Calls
|
||
|
||
system
|
||
......
|
||
|
||
Synopsis:
|
||
int system(const char *command);
|
||
|
||
Request:
|
||
'Fsystem,COMMANDPTR/LEN'
|
||
|
||
Return value:
|
||
If LEN is zero, the return value indicates whether a shell is
|
||
available. A zero return value indicates a shell is not available.
|
||
For non-zero LEN, the value returned is -1 on error and the return
|
||
status of the command otherwise. Only the exit status of the
|
||
command is returned, which is extracted from the host's 'system'
|
||
return value by calling 'WEXITSTATUS(retval)'. In case '/bin/sh'
|
||
could not be executed, 127 is returned.
|
||
|
||
Errors:
|
||
|
||
'EINTR'
|
||
The call was interrupted by the user.
|
||
|
||
GDB takes over the full task of calling the necessary host calls to
|
||
perform the 'system' call. The return value of 'system' on the host is
|
||
simplified before it's returned to the target. Any termination signal
|
||
information from the child process is discarded, and the return value
|
||
consists entirely of the exit status of the called command.
|
||
|
||
Due to security concerns, the 'system' call is by default refused by
|
||
GDB. The user has to allow this call explicitly with the 'set remote
|
||
system-call-allowed 1' command.
|
||
|
||
'set remote system-call-allowed'
|
||
Control whether to allow the 'system' calls in the File I/O
|
||
protocol for the remote target. The default is zero (disabled).
|
||
|
||
'show remote system-call-allowed'
|
||
Show whether the 'system' calls are allowed in the File I/O
|
||
protocol.
|
||
|
||
|
||
File: gdb.info, Node: Protocol-specific Representation of Datatypes, Next: Constants, Prev: List of Supported Calls, Up: File-I/O Remote Protocol Extension
|
||
|
||
E.13.8 Protocol-specific Representation of Datatypes
|
||
----------------------------------------------------
|
||
|
||
* Menu:
|
||
|
||
* Integral Datatypes::
|
||
* Pointer Values::
|
||
* Memory Transfer::
|
||
* struct stat::
|
||
* struct timeval::
|
||
|
||
|
||
File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes
|
||
|
||
Integral Datatypes
|
||
..................
|
||
|
||
The integral datatypes used in the system calls are 'int', 'unsigned
|
||
int', 'long', 'unsigned long', 'mode_t', and 'time_t'.
|
||
|
||
'int', 'unsigned int', 'mode_t' and 'time_t' are implemented as 32
|
||
bit values in this protocol.
|
||
|
||
'long' and 'unsigned long' are implemented as 64 bit types.
|
||
|
||
*Note Limits::, for corresponding MIN and MAX values (similar to
|
||
those in 'limits.h') to allow range checking on host and target.
|
||
|
||
'time_t' datatypes are defined as seconds since the Epoch.
|
||
|
||
All integral datatypes transferred as part of a memory read or write
|
||
of a structured datatype e.g. a 'struct stat' have to be given in big
|
||
endian byte order.
|
||
|
||
|
||
File: gdb.info, Node: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes
|
||
|
||
Pointer Values
|
||
..............
|
||
|
||
Pointers to target data are transmitted as they are. An exception is
|
||
made for pointers to buffers for which the length isn't transmitted as
|
||
part of the function call, namely strings. Strings are transmitted as a
|
||
pointer/length pair, both as hex values, e.g.
|
||
|
||
1aaf/12
|
||
|
||
which is a pointer to data of length 18 bytes at position 0x1aaf. The
|
||
length is defined as the full string length in bytes, including the
|
||
trailing null byte. For example, the string '"hello world"' at address
|
||
0x123456 is transmitted as
|
||
|
||
123456/d
|
||
|
||
|
||
File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes
|
||
|
||
Memory Transfer
|
||
...............
|
||
|
||
Structured data which is transferred using a memory read or write (for
|
||
example, a 'struct stat') is expected to be in a protocol-specific
|
||
format with all scalar multibyte datatypes being big endian.
|
||
Translation to this representation needs to be done both by the target
|
||
before the 'F' packet is sent, and by GDB before it transfers memory to
|
||
the target. Transferred pointers to structured data should point to the
|
||
already-coerced data at any time.
|
||
|
||
|
||
File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes
|
||
|
||
struct stat
|
||
...........
|
||
|
||
The buffer of type 'struct stat' used by the target and GDB is defined
|
||
as follows:
|
||
|
||
struct stat {
|
||
unsigned int st_dev; /* device */
|
||
unsigned int st_ino; /* inode */
|
||
mode_t st_mode; /* protection */
|
||
unsigned int st_nlink; /* number of hard links */
|
||
unsigned int st_uid; /* user ID of owner */
|
||
unsigned int st_gid; /* group ID of owner */
|
||
unsigned int st_rdev; /* device type (if inode device) */
|
||
unsigned long st_size; /* total size, in bytes */
|
||
unsigned long st_blksize; /* blocksize for filesystem I/O */
|
||
unsigned long st_blocks; /* number of blocks allocated */
|
||
time_t st_atime; /* time of last access */
|
||
time_t st_mtime; /* time of last modification */
|
||
time_t st_ctime; /* time of last change */
|
||
};
|
||
|
||
The integral datatypes conform to the definitions given in the
|
||
appropriate section (see *note Integral Datatypes::, for details) so
|
||
this structure is of size 64 bytes.
|
||
|
||
The values of several fields have a restricted meaning and/or range
|
||
of values.
|
||
|
||
'st_dev'
|
||
A value of 0 represents a file, 1 the console.
|
||
|
||
'st_ino'
|
||
No valid meaning for the target. Transmitted unchanged.
|
||
|
||
'st_mode'
|
||
Valid mode bits are described in *note Constants::. Any other bits
|
||
have currently no meaning for the target.
|
||
|
||
'st_uid'
|
||
'st_gid'
|
||
'st_rdev'
|
||
No valid meaning for the target. Transmitted unchanged.
|
||
|
||
'st_atime'
|
||
'st_mtime'
|
||
'st_ctime'
|
||
These values have a host and file system dependent accuracy.
|
||
Especially on Windows hosts, the file system may not support exact
|
||
timing values.
|
||
|
||
The target gets a 'struct stat' of the above representation and is
|
||
responsible for coercing it to the target representation before
|
||
continuing.
|
||
|
||
Note that due to size differences between the host, target, and
|
||
protocol representations of 'struct stat' members, these members could
|
||
eventually get truncated on the target.
|
||
|
||
|
||
File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol-specific Representation of Datatypes
|
||
|
||
struct timeval
|
||
..............
|
||
|
||
The buffer of type 'struct timeval' used by the File-I/O protocol is
|
||
defined as follows:
|
||
|
||
struct timeval {
|
||
time_t tv_sec; /* second */
|
||
long tv_usec; /* microsecond */
|
||
};
|
||
|
||
The integral datatypes conform to the definitions given in the
|
||
appropriate section (see *note Integral Datatypes::, for details) so
|
||
this structure is of size 8 bytes.
|
||
|
||
|
||
File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension
|
||
|
||
E.13.9 Constants
|
||
----------------
|
||
|
||
The following values are used for the constants inside of the protocol.
|
||
GDB and target are responsible for translating these values before and
|
||
after the call as needed.
|
||
|
||
* Menu:
|
||
|
||
* Open Flags::
|
||
* mode_t Values::
|
||
* Errno Values::
|
||
* Lseek Flags::
|
||
* Limits::
|
||
|
||
|
||
File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants
|
||
|
||
Open Flags
|
||
..........
|
||
|
||
All values are given in hexadecimal representation.
|
||
|
||
O_RDONLY 0x0
|
||
O_WRONLY 0x1
|
||
O_RDWR 0x2
|
||
O_APPEND 0x8
|
||
O_CREAT 0x200
|
||
O_TRUNC 0x400
|
||
O_EXCL 0x800
|
||
|
||
|
||
File: gdb.info, Node: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants
|
||
|
||
mode_t Values
|
||
.............
|
||
|
||
All values are given in octal representation.
|
||
|
||
S_IFREG 0100000
|
||
S_IFDIR 040000
|
||
S_IRUSR 0400
|
||
S_IWUSR 0200
|
||
S_IXUSR 0100
|
||
S_IRGRP 040
|
||
S_IWGRP 020
|
||
S_IXGRP 010
|
||
S_IROTH 04
|
||
S_IWOTH 02
|
||
S_IXOTH 01
|
||
|
||
|
||
File: gdb.info, Node: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants
|
||
|
||
Errno Values
|
||
............
|
||
|
||
All values are given in decimal representation.
|
||
|
||
EPERM 1
|
||
ENOENT 2
|
||
EINTR 4
|
||
EBADF 9
|
||
EACCES 13
|
||
EFAULT 14
|
||
EBUSY 16
|
||
EEXIST 17
|
||
ENODEV 19
|
||
ENOTDIR 20
|
||
EISDIR 21
|
||
EINVAL 22
|
||
ENFILE 23
|
||
EMFILE 24
|
||
EFBIG 27
|
||
ENOSPC 28
|
||
ESPIPE 29
|
||
EROFS 30
|
||
ENAMETOOLONG 91
|
||
EUNKNOWN 9999
|
||
|
||
'EUNKNOWN' is used as a fallback error value if a host system returns
|
||
any error value not in the list of supported error numbers.
|
||
|
||
|
||
File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants
|
||
|
||
Lseek Flags
|
||
...........
|
||
|
||
SEEK_SET 0
|
||
SEEK_CUR 1
|
||
SEEK_END 2
|
||
|
||
|
||
File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants
|
||
|
||
Limits
|
||
......
|
||
|
||
All values are given in decimal representation.
|
||
|
||
INT_MIN -2147483648
|
||
INT_MAX 2147483647
|
||
UINT_MAX 4294967295
|
||
LONG_MIN -9223372036854775808
|
||
LONG_MAX 9223372036854775807
|
||
ULONG_MAX 18446744073709551615
|
||
|
||
|
||
File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension
|
||
|
||
E.13.10 File-I/O Examples
|
||
-------------------------
|
||
|
||
Example sequence of a write call, file descriptor 3, buffer is at target
|
||
address 0x1234, 6 bytes should be written:
|
||
|
||
<- Fwrite,3,1234,6
|
||
_request memory read from target_
|
||
-> m1234,6
|
||
<- XXXXXX
|
||
_return "6 bytes written"_
|
||
-> F6
|
||
|
||
Example sequence of a read call, file descriptor 3, buffer is at
|
||
target address 0x1234, 6 bytes should be read:
|
||
|
||
<- Fread,3,1234,6
|
||
_request memory write to target_
|
||
-> X1234,6:XXXXXX
|
||
_return "6 bytes read"_
|
||
-> F6
|
||
|
||
Example sequence of a read call, call fails on the host due to
|
||
invalid file descriptor ('EBADF'):
|
||
|
||
<- Fread,3,1234,6
|
||
-> F-1,9
|
||
|
||
Example sequence of a read call, user presses 'Ctrl-c' before syscall
|
||
on host is called:
|
||
|
||
<- Fread,3,1234,6
|
||
-> F-1,4,C
|
||
<- T02
|
||
|
||
Example sequence of a read call, user presses 'Ctrl-c' after syscall
|
||
on host is called:
|
||
|
||
<- Fread,3,1234,6
|
||
-> X1234,6:XXXXXX
|
||
<- T02
|
||
|
||
|
||
File: gdb.info, Node: Library List Format, Next: Library List Format for SVR4 Targets, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol
|
||
|
||
E.14 Library List Format
|
||
========================
|
||
|
||
On some platforms, a dynamic loader (e.g. 'ld.so') runs in the same
|
||
process as your application to manage libraries. In this case, GDB can
|
||
use the loader's symbol table and normal memory operations to maintain a
|
||
list of shared libraries. On other platforms, the operating system
|
||
manages loaded libraries. GDB can not retrieve the list of currently
|
||
loaded libraries through memory operations, so it uses the
|
||
'qXfer:libraries:read' packet (*note qXfer library list read::) instead.
|
||
The remote stub queries the target's operating system and reports which
|
||
libraries are loaded.
|
||
|
||
The 'qXfer:libraries:read' packet returns an XML document which lists
|
||
loaded libraries and their offsets. Each library has an associated name
|
||
and one or more segment or section base addresses, which report where
|
||
the library was loaded in memory.
|
||
|
||
For the common case of libraries that are fully linked binaries, the
|
||
library should have a list of segments. If the target supports dynamic
|
||
linking of a relocatable object file, its library XML element should
|
||
instead include a list of allocated sections. The segment or section
|
||
bases are start addresses, not relocation offsets; they do not depend on
|
||
the library's link-time base addresses.
|
||
|
||
GDB must be linked with the Expat library to support XML library
|
||
lists. *Note Expat::.
|
||
|
||
A simple memory map, with one loaded library relocated by a single
|
||
offset, looks like this:
|
||
|
||
<library-list>
|
||
<library name="/lib/libc.so.6">
|
||
<segment address="0x10000000"/>
|
||
</library>
|
||
</library-list>
|
||
|
||
Another simple memory map, with one loaded library with three
|
||
allocated sections (.text, .data, .bss), looks like this:
|
||
|
||
<library-list>
|
||
<library name="sharedlib.o">
|
||
<section address="0x10000000"/>
|
||
<section address="0x20000000"/>
|
||
<section address="0x30000000"/>
|
||
</library>
|
||
</library-list>
|
||
|
||
The format of a library list is described by this DTD:
|
||
|
||
<!-- library-list: Root element with versioning -->
|
||
<!ELEMENT library-list (library)*>
|
||
<!ATTLIST library-list version CDATA #FIXED "1.0">
|
||
<!ELEMENT library (segment*, section*)>
|
||
<!ATTLIST library name CDATA #REQUIRED>
|
||
<!ELEMENT segment EMPTY>
|
||
<!ATTLIST segment address CDATA #REQUIRED>
|
||
<!ELEMENT section EMPTY>
|
||
<!ATTLIST section address CDATA #REQUIRED>
|
||
|
||
In addition, segments and section descriptors cannot be mixed within
|
||
a single library element, and you must supply at least one segment or
|
||
section for each library.
|
||
|
||
|
||
File: gdb.info, Node: Library List Format for SVR4 Targets, Next: Memory Map Format, Prev: Library List Format, Up: Remote Protocol
|
||
|
||
E.15 Library List Format for SVR4 Targets
|
||
=========================================
|
||
|
||
On SVR4 platforms GDB can use the symbol table of a dynamic loader (e.g.
|
||
'ld.so') and normal memory operations to maintain a list of shared
|
||
libraries. Still a special library list provided by this packet is more
|
||
efficient for the GDB remote protocol.
|
||
|
||
The 'qXfer:libraries-svr4:read' packet returns an XML document which
|
||
lists loaded libraries and their SVR4 linker parameters. For each
|
||
library on SVR4 target, the following parameters are reported:
|
||
|
||
- 'name', the absolute file name from the 'l_name' field of 'struct
|
||
link_map'.
|
||
- 'lm' with address of 'struct link_map' used for TLS (Thread Local
|
||
Storage) access.
|
||
- 'l_addr', the displacement as read from the field 'l_addr' of
|
||
'struct link_map'. For prelinked libraries this is not an absolute
|
||
memory address. It is a displacement of absolute memory address
|
||
against address the file was prelinked to during the library load.
|
||
- 'l_ld', which is memory address of the 'PT_DYNAMIC' segment
|
||
|
||
Additionally the single 'main-lm' attribute specifies address of
|
||
'struct link_map' used for the main executable. This parameter is used
|
||
for TLS access and its presence is optional.
|
||
|
||
GDB must be linked with the Expat library to support XML SVR4 library
|
||
lists. *Note Expat::.
|
||
|
||
A simple memory map, with two loaded libraries (which do not use
|
||
prelink), looks like this:
|
||
|
||
<library-list-svr4 version="1.0" main-lm="0xe4f8f8">
|
||
<library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000"
|
||
l_ld="0xe4eefc"/>
|
||
<library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000"
|
||
l_ld="0x152350"/>
|
||
</library-list-svr>
|
||
|
||
The format of an SVR4 library list is described by this DTD:
|
||
|
||
<!-- library-list-svr4: Root element with versioning -->
|
||
<!ELEMENT library-list-svr4 (library)*>
|
||
<!ATTLIST library-list-svr4 version CDATA #FIXED "1.0">
|
||
<!ATTLIST library-list-svr4 main-lm CDATA #IMPLIED>
|
||
<!ELEMENT library EMPTY>
|
||
<!ATTLIST library name CDATA #REQUIRED>
|
||
<!ATTLIST library lm CDATA #REQUIRED>
|
||
<!ATTLIST library l_addr CDATA #REQUIRED>
|
||
<!ATTLIST library l_ld CDATA #REQUIRED>
|
||
|
||
|
||
File: gdb.info, Node: Memory Map Format, Next: Thread List Format, Prev: Library List Format for SVR4 Targets, Up: Remote Protocol
|
||
|
||
E.16 Memory Map Format
|
||
======================
|
||
|
||
To be able to write into flash memory, GDB needs to obtain a memory map
|
||
from the target. This section describes the format of the memory map.
|
||
|
||
The memory map is obtained using the 'qXfer:memory-map:read' (*note
|
||
qXfer memory map read::) packet and is an XML document that lists memory
|
||
regions.
|
||
|
||
GDB must be linked with the Expat library to support XML memory maps.
|
||
*Note Expat::.
|
||
|
||
The top-level structure of the document is shown below:
|
||
|
||
<?xml version="1.0"?>
|
||
<!DOCTYPE memory-map
|
||
PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
|
||
"http://sourceware.org/gdb/gdb-memory-map.dtd">
|
||
<memory-map>
|
||
region...
|
||
</memory-map>
|
||
|
||
Each region can be either:
|
||
|
||
* A region of RAM starting at ADDR and extending for LENGTH bytes
|
||
from there:
|
||
|
||
<memory type="ram" start="ADDR" length="LENGTH"/>
|
||
|
||
* A region of read-only memory:
|
||
|
||
<memory type="rom" start="ADDR" length="LENGTH"/>
|
||
|
||
* A region of flash memory, with erasure blocks BLOCKSIZE bytes in
|
||
length:
|
||
|
||
<memory type="flash" start="ADDR" length="LENGTH">
|
||
<property name="blocksize">BLOCKSIZE</property>
|
||
</memory>
|
||
|
||
Regions must not overlap. GDB assumes that areas of memory not
|
||
covered by the memory map are RAM, and uses the ordinary 'M' and 'X'
|
||
packets to write to addresses in such ranges.
|
||
|
||
The formal DTD for memory map format is given below:
|
||
|
||
<!-- ................................................... -->
|
||
<!-- Memory Map XML DTD ................................ -->
|
||
<!-- File: memory-map.dtd .............................. -->
|
||
<!-- .................................... .............. -->
|
||
<!-- memory-map.dtd -->
|
||
<!-- memory-map: Root element with versioning -->
|
||
<!ELEMENT memory-map (memory)*>
|
||
<!ATTLIST memory-map version CDATA #FIXED "1.0.0">
|
||
<!ELEMENT memory (property)*>
|
||
<!-- memory: Specifies a memory region,
|
||
and its type, or device. -->
|
||
<!ATTLIST memory type (ram|rom|flash) #REQUIRED
|
||
start CDATA #REQUIRED
|
||
length CDATA #REQUIRED>
|
||
<!-- property: Generic attribute tag -->
|
||
<!ELEMENT property (#PCDATA | property)*>
|
||
<!ATTLIST property name (blocksize) #REQUIRED>
|
||
|
||
|
||
File: gdb.info, Node: Thread List Format, Next: Traceframe Info Format, Prev: Memory Map Format, Up: Remote Protocol
|
||
|
||
E.17 Thread List Format
|
||
=======================
|
||
|
||
To efficiently update the list of threads and their attributes, GDB
|
||
issues the 'qXfer:threads:read' packet (*note qXfer threads read::) and
|
||
obtains the XML document with the following structure:
|
||
|
||
<?xml version="1.0"?>
|
||
<threads>
|
||
<thread id="id" core="0" name="name">
|
||
... description ...
|
||
</thread>
|
||
</threads>
|
||
|
||
Each 'thread' element must have the 'id' attribute that identifies
|
||
the thread (*note thread-id syntax::). The 'core' attribute, if
|
||
present, specifies which processor core the thread was last executing
|
||
on. The 'name' attribute, if present, specifies the human-readable name
|
||
of the thread. The content of the of 'thread' element is interpreted as
|
||
human-readable auxiliary information. The 'handle' attribute, if
|
||
present, is a hex encoded representation of the thread handle.
|
||
|
||
|
||
File: gdb.info, Node: Traceframe Info Format, Next: Branch Trace Format, Prev: Thread List Format, Up: Remote Protocol
|
||
|
||
E.18 Traceframe Info Format
|
||
===========================
|
||
|
||
To be able to know which objects in the inferior can be examined when
|
||
inspecting a tracepoint hit, GDB needs to obtain the list of memory
|
||
ranges, registers and trace state variables that have been collected in
|
||
a traceframe.
|
||
|
||
This list is obtained using the 'qXfer:traceframe-info:read' (*note
|
||
qXfer traceframe info read::) packet and is an XML document.
|
||
|
||
GDB must be linked with the Expat library to support XML traceframe
|
||
info discovery. *Note Expat::.
|
||
|
||
The top-level structure of the document is shown below:
|
||
|
||
<?xml version="1.0"?>
|
||
<!DOCTYPE traceframe-info
|
||
PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
|
||
"http://sourceware.org/gdb/gdb-traceframe-info.dtd">
|
||
<traceframe-info>
|
||
block...
|
||
</traceframe-info>
|
||
|
||
Each traceframe block can be either:
|
||
|
||
* A region of collected memory starting at ADDR and extending for
|
||
LENGTH bytes from there:
|
||
|
||
<memory start="ADDR" length="LENGTH"/>
|
||
|
||
* A block indicating trace state variable numbered NUMBER has been
|
||
collected:
|
||
|
||
<tvar id="NUMBER"/>
|
||
|
||
The formal DTD for the traceframe info format is given below:
|
||
|
||
<!ELEMENT traceframe-info (memory | tvar)* >
|
||
<!ATTLIST traceframe-info version CDATA #FIXED "1.0">
|
||
|
||
<!ELEMENT memory EMPTY>
|
||
<!ATTLIST memory start CDATA #REQUIRED
|
||
length CDATA #REQUIRED>
|
||
<!ELEMENT tvar>
|
||
<!ATTLIST tvar id CDATA #REQUIRED>
|
||
|
||
|
||
File: gdb.info, Node: Branch Trace Format, Next: Branch Trace Configuration Format, Prev: Traceframe Info Format, Up: Remote Protocol
|
||
|
||
E.19 Branch Trace Format
|
||
========================
|
||
|
||
In order to display the branch trace of an inferior thread, GDB needs to
|
||
obtain the list of branches. This list is represented as list of
|
||
sequential code blocks that are connected via branches. The code in
|
||
each block has been executed sequentially.
|
||
|
||
This list is obtained using the 'qXfer:btrace:read' (*note qXfer
|
||
btrace read::) packet and is an XML document.
|
||
|
||
GDB must be linked with the Expat library to support XML traceframe
|
||
info discovery. *Note Expat::.
|
||
|
||
The top-level structure of the document is shown below:
|
||
|
||
<?xml version="1.0"?>
|
||
<!DOCTYPE btrace
|
||
PUBLIC "+//IDN gnu.org//DTD GDB Branch Trace V1.0//EN"
|
||
"http://sourceware.org/gdb/gdb-btrace.dtd">
|
||
<btrace>
|
||
block...
|
||
</btrace>
|
||
|
||
* A block of sequentially executed instructions starting at BEGIN and
|
||
ending at END:
|
||
|
||
<block begin="BEGIN" end="END"/>
|
||
|
||
The formal DTD for the branch trace format is given below:
|
||
|
||
<!ELEMENT btrace (block* | pt) >
|
||
<!ATTLIST btrace version CDATA #FIXED "1.0">
|
||
|
||
<!ELEMENT block EMPTY>
|
||
<!ATTLIST block begin CDATA #REQUIRED
|
||
end CDATA #REQUIRED>
|
||
|
||
<!ELEMENT pt (pt-config?, raw?)>
|
||
|
||
<!ELEMENT pt-config (cpu?)>
|
||
|
||
<!ELEMENT cpu EMPTY>
|
||
<!ATTLIST cpu vendor CDATA #REQUIRED
|
||
family CDATA #REQUIRED
|
||
model CDATA #REQUIRED
|
||
stepping CDATA #REQUIRED>
|
||
|
||
<!ELEMENT raw (#PCDATA)>
|
||
|
||
|
||
File: gdb.info, Node: Branch Trace Configuration Format, Prev: Branch Trace Format, Up: Remote Protocol
|
||
|
||
E.20 Branch Trace Configuration Format
|
||
======================================
|
||
|
||
For each inferior thread, GDB can obtain the branch trace configuration
|
||
using the 'qXfer:btrace-conf:read' (*note qXfer btrace-conf read::)
|
||
packet.
|
||
|
||
The configuration describes the branch trace format and configuration
|
||
settings for that format. The following information is described:
|
||
|
||
'bts'
|
||
This thread uses the "Branch Trace Store" (BTS) format.
|
||
'size'
|
||
The size of the BTS ring buffer in bytes.
|
||
'pt'
|
||
This thread uses the "Intel Processor Trace" (Intel PT) format.
|
||
'size'
|
||
The size of the Intel PT ring buffer in bytes.
|
||
|
||
GDB must be linked with the Expat library to support XML branch trace
|
||
configuration discovery. *Note Expat::.
|
||
|
||
The formal DTD for the branch trace configuration format is given
|
||
below:
|
||
|
||
<!ELEMENT btrace-conf (bts?, pt?)>
|
||
<!ATTLIST btrace-conf version CDATA #FIXED "1.0">
|
||
|
||
<!ELEMENT bts EMPTY>
|
||
<!ATTLIST bts size CDATA #IMPLIED>
|
||
|
||
<!ELEMENT pt EMPTY>
|
||
<!ATTLIST pt size CDATA #IMPLIED>
|
||
|
||
|
||
File: gdb.info, Node: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top
|
||
|
||
Appendix F The GDB Agent Expression Mechanism
|
||
*********************************************
|
||
|
||
In some applications, it is not feasible for the debugger to interrupt
|
||
the program's execution long enough for the developer to learn anything
|
||
helpful about its behavior. If the program's correctness depends on its
|
||
real-time behavior, delays introduced by a debugger might cause the
|
||
program to fail, even when the code itself is correct. It is useful to
|
||
be able to observe the program's behavior without interrupting it.
|
||
|
||
Using GDB's 'trace' and 'collect' commands, the user can specify
|
||
locations in the program, and arbitrary expressions to evaluate when
|
||
those locations are reached. Later, using the 'tfind' command, she can
|
||
examine the values those expressions had when the program hit the trace
|
||
points. The expressions may also denote objects in memory -- structures
|
||
or arrays, for example -- whose values GDB should record; while visiting
|
||
a particular tracepoint, the user may inspect those objects as if they
|
||
were in memory at that moment. However, because GDB records these
|
||
values without interacting with the user, it can do so quickly and
|
||
unobtrusively, hopefully not disturbing the program's behavior.
|
||
|
||
When GDB is debugging a remote target, the GDB "agent" code running
|
||
on the target computes the values of the expressions itself. To avoid
|
||
having a full symbolic expression evaluator on the agent, GDB translates
|
||
expressions in the source language into a simpler bytecode language, and
|
||
then sends the bytecode to the agent; the agent then executes the
|
||
bytecode, and records the values for GDB to retrieve later.
|
||
|
||
The bytecode language is simple; there are forty-odd opcodes, the
|
||
bulk of which are the usual vocabulary of C operands (addition,
|
||
subtraction, shifts, and so on) and various sizes of literals and memory
|
||
reference operations. The bytecode interpreter operates strictly on
|
||
machine-level values -- various sizes of integers and floating point
|
||
numbers -- and requires no information about types or symbols; thus, the
|
||
interpreter's internal data structures are simple, and each bytecode
|
||
requires only a few native machine instructions to implement it. The
|
||
interpreter is small, and strict limits on the memory and time required
|
||
to evaluate an expression are easy to determine, making it suitable for
|
||
use by the debugging agent in real-time applications.
|
||
|
||
* Menu:
|
||
|
||
* General Bytecode Design:: Overview of the interpreter.
|
||
* Bytecode Descriptions:: What each one does.
|
||
* Using Agent Expressions:: How agent expressions fit into the big picture.
|
||
* Varying Target Capabilities:: How to discover what the target can do.
|
||
* Rationale:: Why we did it this way.
|
||
|
||
|
||
File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions
|
||
|
||
F.1 General Bytecode Design
|
||
===========================
|
||
|
||
The agent represents bytecode expressions as an array of bytes. Each
|
||
instruction is one byte long (thus the term "bytecode"). Some
|
||
instructions are followed by operand bytes; for example, the 'goto'
|
||
instruction is followed by a destination for the jump.
|
||
|
||
The bytecode interpreter is a stack-based machine; most instructions
|
||
pop their operands off the stack, perform some operation, and push the
|
||
result back on the stack for the next instruction to consume. Each
|
||
element of the stack may contain either a integer or a floating point
|
||
value; these values are as many bits wide as the largest integer that
|
||
can be directly manipulated in the source language. Stack elements
|
||
carry no record of their type; bytecode could push a value as an
|
||
integer, then pop it as a floating point value. However, GDB will not
|
||
generate code which does this. In C, one might define the type of a
|
||
stack element as follows:
|
||
union agent_val {
|
||
LONGEST l;
|
||
DOUBLEST d;
|
||
};
|
||
where 'LONGEST' and 'DOUBLEST' are 'typedef' names for the largest
|
||
integer and floating point types on the machine.
|
||
|
||
By the time the bytecode interpreter reaches the end of the
|
||
expression, the value of the expression should be the only value left on
|
||
the stack. For tracing applications, 'trace' bytecodes in the
|
||
expression will have recorded the necessary data, and the value on the
|
||
stack may be discarded. For other applications, like conditional
|
||
breakpoints, the value may be useful.
|
||
|
||
Separate from the stack, the interpreter has two registers:
|
||
'pc'
|
||
The address of the next bytecode to execute.
|
||
|
||
'start'
|
||
The address of the start of the bytecode expression, necessary for
|
||
interpreting the 'goto' and 'if_goto' instructions.
|
||
|
||
Neither of these registers is directly visible to the bytecode language
|
||
itself, but they are useful for defining the meanings of the bytecode
|
||
operations.
|
||
|
||
There are no instructions to perform side effects on the running
|
||
program, or call the program's functions; we assume that these
|
||
expressions are only used for unobtrusive debugging, not for patching
|
||
the running code.
|
||
|
||
Most bytecode instructions do not distinguish between the various
|
||
sizes of values, and operate on full-width values; the upper bits of the
|
||
values are simply ignored, since they do not usually make a difference
|
||
to the value computed. The exceptions to this rule are:
|
||
|
||
memory reference instructions ('ref'N)
|
||
There are distinct instructions to fetch different word sizes from
|
||
memory. Once on the stack, however, the values are treated as
|
||
full-size integers. They may need to be sign-extended; the 'ext'
|
||
instruction exists for this purpose.
|
||
|
||
the sign-extension instruction ('ext' N)
|
||
These clearly need to know which portion of their operand is to be
|
||
extended to occupy the full length of the word.
|
||
|
||
If the interpreter is unable to evaluate an expression completely for
|
||
some reason (a memory location is inaccessible, or a divisor is zero,
|
||
for example), we say that interpretation "terminates with an error".
|
||
This means that the problem is reported back to the interpreter's caller
|
||
in some helpful way. In general, code using agent expressions should
|
||
assume that they may attempt to divide by zero, fetch arbitrary memory
|
||
locations, and misbehave in other ways.
|
||
|
||
Even complicated C expressions compile to a few bytecode
|
||
instructions; for example, the expression 'x + y * z' would typically
|
||
produce code like the following, assuming that 'x' and 'y' live in
|
||
registers, and 'z' is a global variable holding a 32-bit 'int':
|
||
reg 1
|
||
reg 2
|
||
const32 address of z
|
||
ref32
|
||
ext 32
|
||
mul
|
||
add
|
||
end
|
||
|
||
In detail, these mean:
|
||
|
||
'reg 1'
|
||
Push the value of register 1 (presumably holding 'x') onto the
|
||
stack.
|
||
|
||
'reg 2'
|
||
Push the value of register 2 (holding 'y').
|
||
|
||
'const32 address of z'
|
||
Push the address of 'z' onto the stack.
|
||
|
||
'ref32'
|
||
Fetch a 32-bit word from the address at the top of the stack;
|
||
replace the address on the stack with the value. Thus, we replace
|
||
the address of 'z' with 'z''s value.
|
||
|
||
'ext 32'
|
||
Sign-extend the value on the top of the stack from 32 bits to full
|
||
length. This is necessary because 'z' is a signed integer.
|
||
|
||
'mul'
|
||
Pop the top two numbers on the stack, multiply them, and push their
|
||
product. Now the top of the stack contains the value of the
|
||
expression 'y * z'.
|
||
|
||
'add'
|
||
Pop the top two numbers, add them, and push the sum. Now the top
|
||
of the stack contains the value of 'x + y * z'.
|
||
|
||
'end'
|
||
Stop executing; the value left on the stack top is the value to be
|
||
recorded.
|
||
|
||
|
||
File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions
|
||
|
||
F.2 Bytecode Descriptions
|
||
=========================
|
||
|
||
Each bytecode description has the following form:
|
||
|
||
'add' (0x02): A B => A+B
|
||
|
||
Pop the top two stack items, A and B, as integers; push their sum,
|
||
as an integer.
|
||
|
||
In this example, 'add' is the name of the bytecode, and '(0x02)' is
|
||
the one-byte value used to encode the bytecode, in hexadecimal. The
|
||
phrase "A B => A+B" shows the stack before and after the bytecode
|
||
executes. Beforehand, the stack must contain at least two values, A and
|
||
B; since the top of the stack is to the right, B is on the top of the
|
||
stack, and A is underneath it. After execution, the bytecode will have
|
||
popped A and B from the stack, and replaced them with a single value,
|
||
A+B. There may be other values on the stack below those shown, but the
|
||
bytecode affects only those shown.
|
||
|
||
Here is another example:
|
||
|
||
'const8' (0x22) N: => N
|
||
Push the 8-bit integer constant N on the stack, without sign
|
||
extension.
|
||
|
||
In this example, the bytecode 'const8' takes an operand N directly
|
||
from the bytecode stream; the operand follows the 'const8' bytecode
|
||
itself. We write any such operands immediately after the name of the
|
||
bytecode, before the colon, and describe the exact encoding of the
|
||
operand in the bytecode stream in the body of the bytecode description.
|
||
|
||
For the 'const8' bytecode, there are no stack items given before the
|
||
=>; this simply means that the bytecode consumes no values from the
|
||
stack. If a bytecode consumes no values, or produces no values, the
|
||
list on either side of the => may be empty.
|
||
|
||
If a value is written as A, B, or N, then the bytecode treats it as
|
||
an integer. If a value is written is ADDR, then the bytecode treats it
|
||
as an address.
|
||
|
||
We do not fully describe the floating point operations here; although
|
||
this design can be extended in a clean way to handle floating point
|
||
values, they are not of immediate interest to the customer, so we avoid
|
||
describing them, to save time.
|
||
|
||
'float' (0x01): =>
|
||
|
||
Prefix for floating-point bytecodes. Not implemented yet.
|
||
|
||
'add' (0x02): A B => A+B
|
||
Pop two integers from the stack, and push their sum, as an integer.
|
||
|
||
'sub' (0x03): A B => A-B
|
||
Pop two integers from the stack, subtract the top value from the
|
||
next-to-top value, and push the difference.
|
||
|
||
'mul' (0x04): A B => A*B
|
||
Pop two integers from the stack, multiply them, and push the
|
||
product on the stack. Note that, when one multiplies two N-bit
|
||
numbers yielding another N-bit number, it is irrelevant whether the
|
||
numbers are signed or not; the results are the same.
|
||
|
||
'div_signed' (0x05): A B => A/B
|
||
Pop two signed integers from the stack; divide the next-to-top
|
||
value by the top value, and push the quotient. If the divisor is
|
||
zero, terminate with an error.
|
||
|
||
'div_unsigned' (0x06): A B => A/B
|
||
Pop two unsigned integers from the stack; divide the next-to-top
|
||
value by the top value, and push the quotient. If the divisor is
|
||
zero, terminate with an error.
|
||
|
||
'rem_signed' (0x07): A B => A MODULO B
|
||
Pop two signed integers from the stack; divide the next-to-top
|
||
value by the top value, and push the remainder. If the divisor is
|
||
zero, terminate with an error.
|
||
|
||
'rem_unsigned' (0x08): A B => A MODULO B
|
||
Pop two unsigned integers from the stack; divide the next-to-top
|
||
value by the top value, and push the remainder. If the divisor is
|
||
zero, terminate with an error.
|
||
|
||
'lsh' (0x09): A B => A<<B
|
||
Pop two integers from the stack; let A be the next-to-top value,
|
||
and B be the top value. Shift A left by B bits, and push the
|
||
result.
|
||
|
||
'rsh_signed' (0x0a): A B => '(signed)'A>>B
|
||
Pop two integers from the stack; let A be the next-to-top value,
|
||
and B be the top value. Shift A right by B bits, inserting copies
|
||
of the top bit at the high end, and push the result.
|
||
|
||
'rsh_unsigned' (0x0b): A B => A>>B
|
||
Pop two integers from the stack; let A be the next-to-top value,
|
||
and B be the top value. Shift A right by B bits, inserting zero
|
||
bits at the high end, and push the result.
|
||
|
||
'log_not' (0x0e): A => !A
|
||
Pop an integer from the stack; if it is zero, push the value one;
|
||
otherwise, push the value zero.
|
||
|
||
'bit_and' (0x0f): A B => A&B
|
||
Pop two integers from the stack, and push their bitwise 'and'.
|
||
|
||
'bit_or' (0x10): A B => A|B
|
||
Pop two integers from the stack, and push their bitwise 'or'.
|
||
|
||
'bit_xor' (0x11): A B => A^B
|
||
Pop two integers from the stack, and push their bitwise
|
||
exclusive-'or'.
|
||
|
||
'bit_not' (0x12): A => ~A
|
||
Pop an integer from the stack, and push its bitwise complement.
|
||
|
||
'equal' (0x13): A B => A=B
|
||
Pop two integers from the stack; if they are equal, push the value
|
||
one; otherwise, push the value zero.
|
||
|
||
'less_signed' (0x14): A B => A<B
|
||
Pop two signed integers from the stack; if the next-to-top value is
|
||
less than the top value, push the value one; otherwise, push the
|
||
value zero.
|
||
|
||
'less_unsigned' (0x15): A B => A<B
|
||
Pop two unsigned integers from the stack; if the next-to-top value
|
||
is less than the top value, push the value one; otherwise, push the
|
||
value zero.
|
||
|
||
'ext' (0x16) N: A => A, sign-extended from N bits
|
||
Pop an unsigned value from the stack; treating it as an N-bit
|
||
twos-complement value, extend it to full length. This means that
|
||
all bits to the left of bit N-1 (where the least significant bit is
|
||
bit 0) are set to the value of bit N-1. Note that N may be larger
|
||
than or equal to the width of the stack elements of the bytecode
|
||
engine; in this case, the bytecode should have no effect.
|
||
|
||
The number of source bits to preserve, N, is encoded as a single
|
||
byte unsigned integer following the 'ext' bytecode.
|
||
|
||
'zero_ext' (0x2a) N: A => A, zero-extended from N bits
|
||
Pop an unsigned value from the stack; zero all but the bottom N
|
||
bits.
|
||
|
||
The number of source bits to preserve, N, is encoded as a single
|
||
byte unsigned integer following the 'zero_ext' bytecode.
|
||
|
||
'ref8' (0x17): ADDR => A
|
||
'ref16' (0x18): ADDR => A
|
||
'ref32' (0x19): ADDR => A
|
||
'ref64' (0x1a): ADDR => A
|
||
Pop an address ADDR from the stack. For bytecode 'ref'N, fetch an
|
||
N-bit value from ADDR, using the natural target endianness. Push
|
||
the fetched value as an unsigned integer.
|
||
|
||
Note that ADDR may not be aligned in any particular way; the 'refN'
|
||
bytecodes should operate correctly for any address.
|
||
|
||
If attempting to access memory at ADDR would cause a processor
|
||
exception of some sort, terminate with an error.
|
||
|
||
'ref_float' (0x1b): ADDR => D
|
||
'ref_double' (0x1c): ADDR => D
|
||
'ref_long_double' (0x1d): ADDR => D
|
||
'l_to_d' (0x1e): A => D
|
||
'd_to_l' (0x1f): D => A
|
||
Not implemented yet.
|
||
|
||
'dup' (0x28): A => A A
|
||
Push another copy of the stack's top element.
|
||
|
||
'swap' (0x2b): A B => B A
|
||
Exchange the top two items on the stack.
|
||
|
||
'pop' (0x29): A =>
|
||
Discard the top value on the stack.
|
||
|
||
'pick' (0x32) N: A ... B => A ... B A
|
||
Duplicate an item from the stack and push it on the top of the
|
||
stack. N, a single byte, indicates the stack item to copy. If N
|
||
is zero, this is the same as 'dup'; if N is one, it copies the item
|
||
under the top item, etc. If N exceeds the number of items on the
|
||
stack, terminate with an error.
|
||
|
||
'rot' (0x33): A B C => C A B
|
||
Rotate the top three items on the stack. The top item (c) becomes
|
||
the third item, the next-to-top item (b) becomes the top item and
|
||
the third item (a) from the top becomes the next-to-top item.
|
||
|
||
'if_goto' (0x20) OFFSET: A =>
|
||
Pop an integer off the stack; if it is non-zero, branch to the
|
||
given offset in the bytecode string. Otherwise, continue to the
|
||
next instruction in the bytecode stream. In other words, if A is
|
||
non-zero, set the 'pc' register to 'start' + OFFSET. Thus, an
|
||
offset of zero denotes the beginning of the expression.
|
||
|
||
The OFFSET is stored as a sixteen-bit unsigned value, stored
|
||
immediately following the 'if_goto' bytecode. It is always stored
|
||
most significant byte first, regardless of the target's normal
|
||
endianness. The offset is not guaranteed to fall at any particular
|
||
alignment within the bytecode stream; thus, on machines where
|
||
fetching a 16-bit on an unaligned address raises an exception, you
|
||
should fetch the offset one byte at a time.
|
||
|
||
'goto' (0x21) OFFSET: =>
|
||
Branch unconditionally to OFFSET; in other words, set the 'pc'
|
||
register to 'start' + OFFSET.
|
||
|
||
The offset is stored in the same way as for the 'if_goto' bytecode.
|
||
|
||
'const8' (0x22) N: => N
|
||
'const16' (0x23) N: => N
|
||
'const32' (0x24) N: => N
|
||
'const64' (0x25) N: => N
|
||
Push the integer constant N on the stack, without sign extension.
|
||
To produce a small negative value, push a small twos-complement
|
||
value, and then sign-extend it using the 'ext' bytecode.
|
||
|
||
The constant N is stored in the appropriate number of bytes
|
||
following the 'const'B bytecode. The constant N is always stored
|
||
most significant byte first, regardless of the target's normal
|
||
endianness. The constant is not guaranteed to fall at any
|
||
particular alignment within the bytecode stream; thus, on machines
|
||
where fetching a 16-bit on an unaligned address raises an
|
||
exception, you should fetch N one byte at a time.
|
||
|
||
'reg' (0x26) N: => A
|
||
Push the value of register number N, without sign extension. The
|
||
registers are numbered following GDB's conventions.
|
||
|
||
The register number N is encoded as a 16-bit unsigned integer
|
||
immediately following the 'reg' bytecode. It is always stored most
|
||
significant byte first, regardless of the target's normal
|
||
endianness. The register number is not guaranteed to fall at any
|
||
particular alignment within the bytecode stream; thus, on machines
|
||
where fetching a 16-bit on an unaligned address raises an
|
||
exception, you should fetch the register number one byte at a time.
|
||
|
||
'getv' (0x2c) N: => V
|
||
Push the value of trace state variable number N, without sign
|
||
extension.
|
||
|
||
The variable number N is encoded as a 16-bit unsigned integer
|
||
immediately following the 'getv' bytecode. It is always stored
|
||
most significant byte first, regardless of the target's normal
|
||
endianness. The variable number is not guaranteed to fall at any
|
||
particular alignment within the bytecode stream; thus, on machines
|
||
where fetching a 16-bit on an unaligned address raises an
|
||
exception, you should fetch the register number one byte at a time.
|
||
|
||
'setv' (0x2d) N: V => V
|
||
Set trace state variable number N to the value found on the top of
|
||
the stack. The stack is unchanged, so that the value is readily
|
||
available if the assignment is part of a larger expression. The
|
||
handling of N is as described for 'getv'.
|
||
|
||
'trace' (0x0c): ADDR SIZE =>
|
||
Record the contents of the SIZE bytes at ADDR in a trace buffer,
|
||
for later retrieval by GDB.
|
||
|
||
'trace_quick' (0x0d) SIZE: ADDR => ADDR
|
||
Record the contents of the SIZE bytes at ADDR in a trace buffer,
|
||
for later retrieval by GDB. SIZE is a single byte unsigned integer
|
||
following the 'trace' opcode.
|
||
|
||
This bytecode is equivalent to the sequence 'dup const8 SIZE
|
||
trace', but we provide it anyway to save space in bytecode strings.
|
||
|
||
'trace16' (0x30) SIZE: ADDR => ADDR
|
||
Identical to trace_quick, except that SIZE is a 16-bit big-endian
|
||
unsigned integer, not a single byte. This should probably have
|
||
been named 'trace_quick16', for consistency.
|
||
|
||
'tracev' (0x2e) N: => A
|
||
Record the value of trace state variable number N in the trace
|
||
buffer. The handling of N is as described for 'getv'.
|
||
|
||
'tracenz' (0x2f) ADDR SIZE =>
|
||
Record the bytes at ADDR in a trace buffer, for later retrieval by
|
||
GDB. Stop at either the first zero byte, or when SIZE bytes have
|
||
been recorded, whichever occurs first.
|
||
|
||
'printf' (0x34) NUMARGS STRING =>
|
||
Do a formatted print, in the style of the C function 'printf').
|
||
The value of NUMARGS is the number of arguments to expect on the
|
||
stack, while STRING is the format string, prefixed with a two-byte
|
||
length. The last byte of the string must be zero, and is included
|
||
in the length. The format string includes escaped sequences just
|
||
as it appears in C source, so for instance the format string
|
||
'"\t%d\n"' is six characters long, and the output will consist of a
|
||
tab character, a decimal number, and a newline. At the top of the
|
||
stack, above the values to be printed, this bytecode will pop a
|
||
"function" and "channel". If the function is nonzero, then the
|
||
target may treat it as a function and call it, passing the channel
|
||
as a first argument, as with the C function 'fprintf'. If the
|
||
function is zero, then the target may simply call a standard
|
||
formatted print function of its choice. In all, this bytecode pops
|
||
2 + NUMARGS stack elements, and pushes nothing.
|
||
|
||
'end' (0x27): =>
|
||
Stop executing bytecode; the result should be the top element of
|
||
the stack. If the purpose of the expression was to compute an
|
||
lvalue or a range of memory, then the next-to-top of the stack is
|
||
the lvalue's address, and the top of the stack is the lvalue's
|
||
size, in bytes.
|
||
|
||
|
||
File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions
|
||
|
||
F.3 Using Agent Expressions
|
||
===========================
|
||
|
||
Agent expressions can be used in several different ways by GDB, and the
|
||
debugger can generate different bytecode sequences as appropriate.
|
||
|
||
One possibility is to do expression evaluation on the target rather
|
||
than the host, such as for the conditional of a conditional tracepoint.
|
||
In such a case, GDB compiles the source expression into a bytecode
|
||
sequence that simply gets values from registers or memory, does
|
||
arithmetic, and returns a result.
|
||
|
||
Another way to use agent expressions is for tracepoint data
|
||
collection. GDB generates a different bytecode sequence for collection;
|
||
in addition to bytecodes that do the calculation, GDB adds 'trace'
|
||
bytecodes to save the pieces of memory that were used.
|
||
|
||
* The user selects trace points in the program's code at which GDB
|
||
should collect data.
|
||
|
||
* The user specifies expressions to evaluate at each trace point.
|
||
These expressions may denote objects in memory, in which case those
|
||
objects' contents are recorded as the program runs, or computed
|
||
values, in which case the values themselves are recorded.
|
||
|
||
* GDB transmits the tracepoints and their associated expressions to
|
||
the GDB agent, running on the debugging target.
|
||
|
||
* The agent arranges to be notified when a trace point is hit.
|
||
|
||
* When execution on the target reaches a trace point, the agent
|
||
evaluates the expressions associated with that trace point, and
|
||
records the resulting values and memory ranges.
|
||
|
||
* Later, when the user selects a given trace event and inspects the
|
||
objects and expression values recorded, GDB talks to the agent to
|
||
retrieve recorded data as necessary to meet the user's requests.
|
||
If the user asks to see an object whose contents have not been
|
||
recorded, GDB reports an error.
|
||
|
||
|
||
File: gdb.info, Node: Varying Target Capabilities, Next: Rationale, Prev: Using Agent Expressions, Up: Agent Expressions
|
||
|
||
F.4 Varying Target Capabilities
|
||
===============================
|
||
|
||
Some targets don't support floating-point, and some would rather not
|
||
have to deal with 'long long' operations. Also, different targets will
|
||
have different stack sizes, and different bytecode buffer lengths.
|
||
|
||
Thus, GDB needs a way to ask the target about itself. We haven't
|
||
worked out the details yet, but in general, GDB should be able to send
|
||
the target a packet asking it to describe itself. The reply should be a
|
||
packet whose length is explicit, so we can add new information to the
|
||
packet in future revisions of the agent, without confusing old versions
|
||
of GDB, and it should contain a version number. It should contain at
|
||
least the following information:
|
||
|
||
* whether floating point is supported
|
||
|
||
* whether 'long long' is supported
|
||
|
||
* maximum acceptable size of bytecode stack
|
||
|
||
* maximum acceptable length of bytecode expressions
|
||
|
||
* which registers are actually available for collection
|
||
|
||
* whether the target supports disabled tracepoints
|
||
|
||
|
||
File: gdb.info, Node: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions
|
||
|
||
F.5 Rationale
|
||
=============
|
||
|
||
Some of the design decisions apparent above are arguable.
|
||
|
||
What about stack overflow/underflow?
|
||
GDB should be able to query the target to discover its stack size.
|
||
Given that information, GDB can determine at translation time
|
||
whether a given expression will overflow the stack. But this spec
|
||
isn't about what kinds of error-checking GDB ought to do.
|
||
|
||
Why are you doing everything in LONGEST?
|
||
|
||
Speed isn't important, but agent code size is; using LONGEST brings
|
||
in a bunch of support code to do things like division, etc. So
|
||
this is a serious concern.
|
||
|
||
First, note that you don't need different bytecodes for different
|
||
operand sizes. You can generate code without _knowing_ how big the
|
||
stack elements actually are on the target. If the target only
|
||
supports 32-bit ints, and you don't send any 64-bit bytecodes,
|
||
everything just works. The observation here is that the MIPS and
|
||
the Alpha have only fixed-size registers, and you can still get C's
|
||
semantics even though most instructions only operate on full-sized
|
||
words. You just need to make sure everything is properly
|
||
sign-extended at the right times. So there is no need for 32- and
|
||
64-bit variants of the bytecodes. Just implement everything using
|
||
the largest size you support.
|
||
|
||
GDB should certainly check to see what sizes the target supports,
|
||
so the user can get an error earlier, rather than later. But this
|
||
information is not necessary for correctness.
|
||
|
||
Why don't you have '>' or '<=' operators?
|
||
I want to keep the interpreter small, and we don't need them. We
|
||
can combine the 'less_' opcodes with 'log_not', and swap the order
|
||
of the operands, yielding all four asymmetrical comparison
|
||
operators. For example, '(x <= y)' is '! (x > y)', which is '! (y
|
||
< x)'.
|
||
|
||
Why do you have 'log_not'?
|
||
Why do you have 'ext'?
|
||
Why do you have 'zero_ext'?
|
||
These are all easily synthesized from other instructions, but I
|
||
expect them to be used frequently, and they're simple, so I include
|
||
them to keep bytecode strings short.
|
||
|
||
'log_not' is equivalent to 'const8 0 equal'; it's used in half the
|
||
relational operators.
|
||
|
||
'ext N' is equivalent to 'const8 S-N lsh const8 S-N rsh_signed',
|
||
where S is the size of the stack elements; it follows 'refM' and
|
||
REG bytecodes when the value should be signed. See the next
|
||
bulleted item.
|
||
|
||
'zero_ext N' is equivalent to 'constM MASK log_and'; it's used
|
||
whenever we push the value of a register, because we can't assume
|
||
the upper bits of the register aren't garbage.
|
||
|
||
Why not have sign-extending variants of the 'ref' operators?
|
||
Because that would double the number of 'ref' operators, and we
|
||
need the 'ext' bytecode anyway for accessing bitfields.
|
||
|
||
Why not have constant-address variants of the 'ref' operators?
|
||
Because that would double the number of 'ref' operators again, and
|
||
'const32 ADDRESS ref32' is only one byte longer.
|
||
|
||
Why do the 'refN' operators have to support unaligned fetches?
|
||
GDB will generate bytecode that fetches multi-byte values at
|
||
unaligned addresses whenever the executable's debugging information
|
||
tells it to. Furthermore, GDB does not know the value the pointer
|
||
will have when GDB generates the bytecode, so it cannot determine
|
||
whether a particular fetch will be aligned or not.
|
||
|
||
In particular, structure bitfields may be several bytes long, but
|
||
follow no alignment rules; members of packed structures are not
|
||
necessarily aligned either.
|
||
|
||
In general, there are many cases where unaligned references occur
|
||
in correct C code, either at the programmer's explicit request, or
|
||
at the compiler's discretion. Thus, it is simpler to make the GDB
|
||
agent bytecodes work correctly in all circumstances than to make
|
||
GDB guess in each case whether the compiler did the usual thing.
|
||
|
||
Why are there no side-effecting operators?
|
||
Because our current client doesn't want them? That's a cheap
|
||
answer. I think the real answer is that I'm afraid of implementing
|
||
function calls. We should re-visit this issue after the present
|
||
contract is delivered.
|
||
|
||
Why aren't the 'goto' ops PC-relative?
|
||
The interpreter has the base address around anyway for PC bounds
|
||
checking, and it seemed simpler.
|
||
|
||
Why is there only one offset size for the 'goto' ops?
|
||
Offsets are currently sixteen bits. I'm not happy with this
|
||
situation either:
|
||
|
||
Suppose we have multiple branch ops with different offset sizes.
|
||
As I generate code left-to-right, all my jumps are forward jumps
|
||
(there are no loops in expressions), so I never know the target
|
||
when I emit the jump opcode. Thus, I have to either always assume
|
||
the largest offset size, or do jump relaxation on the code after I
|
||
generate it, which seems like a big waste of time.
|
||
|
||
I can imagine a reasonable expression being longer than 256 bytes.
|
||
I can't imagine one being longer than 64k. Thus, we need 16-bit
|
||
offsets. This kind of reasoning is so bogus, but relaxation is
|
||
pathetic.
|
||
|
||
The other approach would be to generate code right-to-left. Then
|
||
I'd always know my offset size. That might be fun.
|
||
|
||
Where is the function call bytecode?
|
||
|
||
When we add side-effects, we should add this.
|
||
|
||
Why does the 'reg' bytecode take a 16-bit register number?
|
||
|
||
Intel's IA-64 architecture has 128 general-purpose registers, and
|
||
128 floating-point registers, and I'm sure it has some random
|
||
control registers.
|
||
|
||
Why do we need 'trace' and 'trace_quick'?
|
||
Because GDB needs to record all the memory contents and registers
|
||
an expression touches. If the user wants to evaluate an expression
|
||
'x->y->z', the agent must record the values of 'x' and 'x->y' as
|
||
well as the value of 'x->y->z'.
|
||
|
||
Don't the 'trace' bytecodes make the interpreter less general?
|
||
They do mean that the interpreter contains special-purpose code,
|
||
but that doesn't mean the interpreter can only be used for that
|
||
purpose. If an expression doesn't use the 'trace' bytecodes, they
|
||
don't get in its way.
|
||
|
||
Why doesn't 'trace_quick' consume its arguments the way everything else does?
|
||
In general, you do want your operators to consume their arguments;
|
||
it's consistent, and generally reduces the amount of stack
|
||
rearrangement necessary. However, 'trace_quick' is a kludge to
|
||
save space; it only exists so we needn't write 'dup const8 SIZE
|
||
trace' before every memory reference. Therefore, it's okay for it
|
||
not to consume its arguments; it's meant for a specific context in
|
||
which we know exactly what it should do with the stack. If we're
|
||
going to have a kludge, it should be an effective kludge.
|
||
|
||
Why does 'trace16' exist?
|
||
That opcode was added by the customer that contracted Cygnus for
|
||
the data tracing work. I personally think it is unnecessary;
|
||
objects that large will be quite rare, so it is okay to use 'dup
|
||
const16 SIZE trace' in those cases.
|
||
|
||
Whatever we decide to do with 'trace16', we should at least leave
|
||
opcode 0x30 reserved, to remain compatible with the customer who
|
||
added it.
|
||
|
||
|
||
File: gdb.info, Node: Target Descriptions, Next: Operating System Information, Prev: Agent Expressions, Up: Top
|
||
|
||
Appendix G Target Descriptions
|
||
******************************
|
||
|
||
One of the challenges of using GDB to debug embedded systems is that
|
||
there are so many minor variants of each processor architecture in use.
|
||
It is common practice for vendors to start with a standard processor
|
||
core -- ARM, PowerPC, or MIPS, for example -- and then make changes to
|
||
adapt it to a particular market niche. Some architectures have hundreds
|
||
of variants, available from dozens of vendors. This leads to a number
|
||
of problems:
|
||
|
||
* With so many different customized processors, it is difficult for
|
||
the GDB maintainers to keep up with the changes.
|
||
* Since individual variants may have short lifetimes or limited
|
||
audiences, it may not be worthwhile to carry information about
|
||
every variant in the GDB source tree.
|
||
* When GDB does support the architecture of the embedded system at
|
||
hand, the task of finding the correct architecture name to give the
|
||
'set architecture' command can be error-prone.
|
||
|
||
To address these problems, the GDB remote protocol allows a target
|
||
system to not only identify itself to GDB, but to actually describe its
|
||
own features. This lets GDB support processor variants it has never
|
||
seen before -- to the extent that the descriptions are accurate, and
|
||
that GDB understands them.
|
||
|
||
GDB must be linked with the Expat library to support XML target
|
||
descriptions. *Note Expat::.
|
||
|
||
* Menu:
|
||
|
||
* Retrieving Descriptions:: How descriptions are fetched from a target.
|
||
* Target Description Format:: The contents of a target description.
|
||
* Predefined Target Types:: Standard types available for target
|
||
descriptions.
|
||
* Enum Target Types:: How to define enum target types.
|
||
* Standard Target Features:: Features GDB knows about.
|
||
|
||
|
||
File: gdb.info, Node: Retrieving Descriptions, Next: Target Description Format, Up: Target Descriptions
|
||
|
||
G.1 Retrieving Descriptions
|
||
===========================
|
||
|
||
Target descriptions can be read from the target automatically, or
|
||
specified by the user manually. The default behavior is to read the
|
||
description from the target. GDB retrieves it via the remote protocol
|
||
using 'qXfer' requests (*note qXfer: General Query Packets.). The ANNEX
|
||
in the 'qXfer' packet will be 'target.xml'. The contents of the
|
||
'target.xml' annex are an XML document, of the form described in *note
|
||
Target Description Format::.
|
||
|
||
Alternatively, you can specify a file to read for the target
|
||
description. If a file is set, the target will not be queried. The
|
||
commands to specify a file are:
|
||
|
||
'set tdesc filename PATH'
|
||
Read the target description from PATH.
|
||
|
||
'unset tdesc filename'
|
||
Do not read the XML target description from a file. GDB will use
|
||
the description supplied by the current target.
|
||
|
||
'show tdesc filename'
|
||
Show the filename to read for a target description, if any.
|
||
|
||
|
||
File: gdb.info, Node: Target Description Format, Next: Predefined Target Types, Prev: Retrieving Descriptions, Up: Target Descriptions
|
||
|
||
G.2 Target Description Format
|
||
=============================
|
||
|
||
A target description annex is an XML (http://www.w3.org/XML/) document
|
||
which complies with the Document Type Definition provided in the GDB
|
||
sources in 'gdb/features/gdb-target.dtd'. This means you can use
|
||
generally available tools like 'xmllint' to check that your feature
|
||
descriptions are well-formed and valid. However, to help people
|
||
unfamiliar with XML write descriptions for their targets, we also
|
||
describe the grammar here.
|
||
|
||
Target descriptions can identify the architecture of the remote
|
||
target and (for some architectures) provide information about custom
|
||
register sets. They can also identify the OS ABI of the remote target.
|
||
GDB can use this information to autoconfigure for your target, or to
|
||
warn you if you connect to an unsupported target.
|
||
|
||
Here is a simple target description:
|
||
|
||
<target version="1.0">
|
||
<architecture>i386:x86-64</architecture>
|
||
</target>
|
||
|
||
This minimal description only says that the target uses the x86-64
|
||
architecture.
|
||
|
||
A target description has the following overall form, with [ ] marking
|
||
optional elements and ... marking repeatable elements. The elements are
|
||
explained further below.
|
||
|
||
<?xml version="1.0"?>
|
||
<!DOCTYPE target SYSTEM "gdb-target.dtd">
|
||
<target version="1.0">
|
||
[ARCHITECTURE]
|
||
[OSABI]
|
||
[COMPATIBLE]
|
||
[FEATURE...]
|
||
</target>
|
||
|
||
The description is generally insensitive to whitespace and line breaks,
|
||
under the usual common-sense rules. The XML version declaration and
|
||
document type declaration can generally be omitted (GDB does not require
|
||
them), but specifying them may be useful for XML validation tools. The
|
||
'version' attribute for '<target>' may also be omitted, but we recommend
|
||
including it; if future versions of GDB use an incompatible revision of
|
||
'gdb-target.dtd', they will detect and report the version mismatch.
|
||
|
||
G.2.1 Inclusion
|
||
---------------
|
||
|
||
It can sometimes be valuable to split a target description up into
|
||
several different annexes, either for organizational purposes, or to
|
||
share files between different possible target descriptions. You can
|
||
divide a description into multiple files by replacing any element of the
|
||
target description with an inclusion directive of the form:
|
||
|
||
<xi:include href="DOCUMENT"/>
|
||
|
||
When GDB encounters an element of this form, it will retrieve the named
|
||
XML DOCUMENT, and replace the inclusion directive with the contents of
|
||
that document. If the current description was read using 'qXfer', then
|
||
so will be the included document; DOCUMENT will be interpreted as the
|
||
name of an annex. If the current description was read from a file, GDB
|
||
will look for DOCUMENT as a file in the same directory where it found
|
||
the original description.
|
||
|
||
G.2.2 Architecture
|
||
------------------
|
||
|
||
An '<architecture>' element has this form:
|
||
|
||
<architecture>ARCH</architecture>
|
||
|
||
ARCH is one of the architectures from the set accepted by 'set
|
||
architecture' (*note Specifying a Debugging Target: Targets.).
|
||
|
||
G.2.3 OS ABI
|
||
------------
|
||
|
||
This optional field was introduced in GDB version 7.0. Previous
|
||
versions of GDB ignore it.
|
||
|
||
An '<osabi>' element has this form:
|
||
|
||
<osabi>ABI-NAME</osabi>
|
||
|
||
ABI-NAME is an OS ABI name from the same selection accepted by
|
||
'set osabi' (*note Configuring the Current ABI: ABI.).
|
||
|
||
G.2.4 Compatible Architecture
|
||
-----------------------------
|
||
|
||
This optional field was introduced in GDB version 7.0. Previous
|
||
versions of GDB ignore it.
|
||
|
||
A '<compatible>' element has this form:
|
||
|
||
<compatible>ARCH</compatible>
|
||
|
||
ARCH is one of the architectures from the set accepted by 'set
|
||
architecture' (*note Specifying a Debugging Target: Targets.).
|
||
|
||
A '<compatible>' element is used to specify that the target is able
|
||
to run binaries in some other than the main target architecture given by
|
||
the '<architecture>' element. For example, on the Cell Broadband
|
||
Engine, the main architecture is 'powerpc:common' or 'powerpc:common64',
|
||
but the system is able to run binaries in the 'spu' architecture as
|
||
well. The way to describe this capability with '<compatible>' is as
|
||
follows:
|
||
|
||
<architecture>powerpc:common</architecture>
|
||
<compatible>spu</compatible>
|
||
|
||
G.2.5 Features
|
||
--------------
|
||
|
||
Each '<feature>' describes some logical portion of the target system.
|
||
Features are currently used to describe available CPU registers and the
|
||
types of their contents. A '<feature>' element has this form:
|
||
|
||
<feature name="NAME">
|
||
[TYPE...]
|
||
REG...
|
||
</feature>
|
||
|
||
Each feature's name should be unique within the description. The name
|
||
of a feature does not matter unless GDB has some special knowledge of
|
||
the contents of that feature; if it does, the feature should have its
|
||
standard name. *Note Standard Target Features::.
|
||
|
||
G.2.6 Types
|
||
-----------
|
||
|
||
Any register's value is a collection of bits which GDB must interpret.
|
||
The default interpretation is a two's complement integer, but other
|
||
types can be requested by name in the register description. Some
|
||
predefined types are provided by GDB (*note Predefined Target Types::),
|
||
and the description can define additional composite and enum types.
|
||
|
||
Each type element must have an 'id' attribute, which gives a unique
|
||
(within the containing '<feature>') name to the type. Types must be
|
||
defined before they are used.
|
||
|
||
Some targets offer vector registers, which can be treated as arrays
|
||
of scalar elements. These types are written as '<vector>' elements,
|
||
specifying the array element type, TYPE, and the number of elements,
|
||
COUNT:
|
||
|
||
<vector id="ID" type="TYPE" count="COUNT"/>
|
||
|
||
If a register's value is usefully viewed in multiple ways, define it
|
||
with a union type containing the useful representations. The '<union>'
|
||
element contains one or more '<field>' elements, each of which has a
|
||
NAME and a TYPE:
|
||
|
||
<union id="ID">
|
||
<field name="NAME" type="TYPE"/>
|
||
...
|
||
</union>
|
||
|
||
If a register's value is composed from several separate values,
|
||
define it with either a structure type or a flags type. A flags type
|
||
may only contain bitfields. A structure type may either contain only
|
||
bitfields or contain no bitfields. If the value contains only
|
||
bitfields, its total size in bytes must be specified.
|
||
|
||
Non-bitfield values have a NAME and TYPE.
|
||
|
||
<struct id="ID">
|
||
<field name="NAME" type="TYPE"/>
|
||
...
|
||
</struct>
|
||
|
||
Both NAME and TYPE values are required. No implicit padding is
|
||
added.
|
||
|
||
Bitfield values have a NAME, START, END and TYPE.
|
||
|
||
<struct id="ID" size="SIZE">
|
||
<field name="NAME" start="START" end="END" type="TYPE"/>
|
||
...
|
||
</struct>
|
||
|
||
<flags id="ID" size="SIZE">
|
||
<field name="NAME" start="START" end="END" type="TYPE"/>
|
||
...
|
||
</flags>
|
||
|
||
The NAME value is required. Bitfield values may be named with the
|
||
empty string, '""', in which case the field is "filler" and its value is
|
||
not printed. Not all bits need to be specified, so "filler" fields are
|
||
optional.
|
||
|
||
The START and END values are required, and TYPE is optional. The
|
||
field's START must be less than or equal to its END, and zero represents
|
||
the least significant bit.
|
||
|
||
The default value of TYPE is 'bool' for single bit fields, and an
|
||
unsigned integer otherwise.
|
||
|
||
Which to choose? Structures or flags?
|
||
|
||
Registers defined with 'flags' have these advantages over defining
|
||
them with 'struct':
|
||
|
||
* Arithmetic may be performed on them as if they were integers.
|
||
* They are printed in a more readable fashion.
|
||
|
||
Registers defined with 'struct' have one advantage over defining them
|
||
with 'flags':
|
||
|
||
* One can fetch individual fields like in 'C'.
|
||
|
||
(gdb) print $my_struct_reg.field3
|
||
$1 = 42
|
||
|
||
G.2.7 Registers
|
||
---------------
|
||
|
||
Each register is represented as an element with this form:
|
||
|
||
<reg name="NAME"
|
||
bitsize="SIZE"
|
||
[regnum="NUM"]
|
||
[save-restore="SAVE-RESTORE"]
|
||
[type="TYPE"]
|
||
[group="GROUP"]/>
|
||
|
||
The components are as follows:
|
||
|
||
NAME
|
||
The register's name; it must be unique within the target
|
||
description.
|
||
|
||
BITSIZE
|
||
The register's size, in bits.
|
||
|
||
REGNUM
|
||
The register's number. If omitted, a register's number is one
|
||
greater than that of the previous register (either in the current
|
||
feature or in a preceding feature); the first register in the
|
||
target description defaults to zero. This register number is used
|
||
to read or write the register; e.g. it is used in the remote 'p'
|
||
and 'P' packets, and registers appear in the 'g' and 'G' packets in
|
||
order of increasing register number.
|
||
|
||
SAVE-RESTORE
|
||
Whether the register should be preserved across inferior function
|
||
calls; this must be either 'yes' or 'no'. The default is 'yes',
|
||
which is appropriate for most registers except for some system
|
||
control registers; this is not related to the target's ABI.
|
||
|
||
TYPE
|
||
The type of the register. It may be a predefined type, a type
|
||
defined in the current feature, or one of the special types 'int'
|
||
and 'float'. 'int' is an integer type of the correct size for
|
||
BITSIZE, and 'float' is a floating point type (in the
|
||
architecture's normal floating point format) of the correct size
|
||
for BITSIZE. The default is 'int'.
|
||
|
||
GROUP
|
||
The register group to which this register belongs. It can be one
|
||
of the standard register groups 'general', 'float', 'vector' or an
|
||
arbitrary string. Group names should be limited to alphanumeric
|
||
characters. If a group name is made up of multiple words the words
|
||
may be separated by hyphens; e.g. 'special-group' or
|
||
'ultra-special-group'. If no GROUP is specified, GDB will not
|
||
display the register in 'info registers'.
|
||
|
||
|
||
File: gdb.info, Node: Predefined Target Types, Next: Enum Target Types, Prev: Target Description Format, Up: Target Descriptions
|
||
|
||
G.3 Predefined Target Types
|
||
===========================
|
||
|
||
Type definitions in the self-description can build up composite types
|
||
from basic building blocks, but can not define fundamental types.
|
||
Instead, standard identifiers are provided by GDB for the fundamental
|
||
types. The currently supported types are:
|
||
|
||
'bool'
|
||
Boolean type, occupying a single bit.
|
||
|
||
'int8'
|
||
'int16'
|
||
'int24'
|
||
'int32'
|
||
'int64'
|
||
'int128'
|
||
Signed integer types holding the specified number of bits.
|
||
|
||
'uint8'
|
||
'uint16'
|
||
'uint24'
|
||
'uint32'
|
||
'uint64'
|
||
'uint128'
|
||
Unsigned integer types holding the specified number of bits.
|
||
|
||
'code_ptr'
|
||
'data_ptr'
|
||
Pointers to unspecified code and data. The program counter and any
|
||
dedicated return address register may be marked as code pointers;
|
||
printing a code pointer converts it into a symbolic address. The
|
||
stack pointer and any dedicated address registers may be marked as
|
||
data pointers.
|
||
|
||
'ieee_single'
|
||
Single precision IEEE floating point.
|
||
|
||
'ieee_double'
|
||
Double precision IEEE floating point.
|
||
|
||
'arm_fpa_ext'
|
||
The 12-byte extended precision format used by ARM FPA registers.
|
||
|
||
'i387_ext'
|
||
The 10-byte extended precision format used by x87 registers.
|
||
|
||
'i386_eflags'
|
||
32bit EFLAGS register used by x86.
|
||
|
||
'i386_mxcsr'
|
||
32bit MXCSR register used by x86.
|
||
|
||
|
||
File: gdb.info, Node: Enum Target Types, Next: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions
|
||
|
||
G.4 Enum Target Types
|
||
=====================
|
||
|
||
Enum target types are useful in 'struct' and 'flags' register
|
||
descriptions. *Note Target Description Format::.
|
||
|
||
Enum types have a name, size and a list of name/value pairs.
|
||
|
||
<enum id="ID" size="SIZE">
|
||
<evalue name="NAME" value="VALUE"/>
|
||
...
|
||
</enum>
|
||
|
||
Enums must be defined before they are used.
|
||
|
||
<enum id="levels_type" size="4">
|
||
<evalue name="low" value="0"/>
|
||
<evalue name="high" value="1"/>
|
||
</enum>
|
||
<flags id="flags_type" size="4">
|
||
<field name="X" start="0"/>
|
||
<field name="LEVEL" start="1" end="1" type="levels_type"/>
|
||
</flags>
|
||
<reg name="flags" bitsize="32" type="flags_type"/>
|
||
|
||
Given that description, a value of 3 for the 'flags' register would
|
||
be printed as:
|
||
|
||
(gdb) info register flags
|
||
flags 0x3 [ X LEVEL=high ]
|
||
|
||
|
||
File: gdb.info, Node: Standard Target Features, Prev: Enum Target Types, Up: Target Descriptions
|
||
|
||
G.5 Standard Target Features
|
||
============================
|
||
|
||
A target description must contain either no registers or all the
|
||
target's registers. If the description contains no registers, then GDB
|
||
will assume a default register layout, selected based on the
|
||
architecture. If the description contains any registers, the default
|
||
layout will not be used; the standard registers must be described in the
|
||
target description, in such a way that GDB can recognize them.
|
||
|
||
This is accomplished by giving specific names to feature elements
|
||
which contain standard registers. GDB will look for features with those
|
||
names and verify that they contain the expected registers; if any known
|
||
feature is missing required registers, or if any required feature is
|
||
missing, GDB will reject the target description. You can add additional
|
||
registers to any of the standard features -- GDB will display them just
|
||
as if they were added to an unrecognized feature.
|
||
|
||
This section lists the known features and their expected contents.
|
||
Sample XML documents for these features are included in the GDB source
|
||
tree, in the directory 'gdb/features'.
|
||
|
||
Names recognized by GDB should include the name of the company or
|
||
organization which selected the name, and the overall architecture to
|
||
which the feature applies; so e.g. the feature containing ARM core
|
||
registers is named 'org.gnu.gdb.arm.core'.
|
||
|
||
The names of registers are not case sensitive for the purpose of
|
||
recognizing standard features, but GDB will only display registers using
|
||
the capitalization used in the description.
|
||
|
||
* Menu:
|
||
|
||
* AArch64 Features::
|
||
* ARC Features::
|
||
* ARM Features::
|
||
* i386 Features::
|
||
* MicroBlaze Features::
|
||
* MIPS Features::
|
||
* M68K Features::
|
||
* NDS32 Features::
|
||
* Nios II Features::
|
||
* OpenRISC 1000 Features::
|
||
* PowerPC Features::
|
||
* RISC-V Features::
|
||
* RX Features::
|
||
* S/390 and System z Features::
|
||
* Sparc Features::
|
||
* TIC6x Features::
|
||
|
||
|
||
File: gdb.info, Node: AArch64 Features, Next: ARC Features, Up: Standard Target Features
|
||
|
||
G.5.1 AArch64 Features
|
||
----------------------
|
||
|
||
The 'org.gnu.gdb.aarch64.core' feature is required for AArch64 targets.
|
||
It should contain registers 'x0' through 'x30', 'sp', 'pc', and 'cpsr'.
|
||
|
||
The 'org.gnu.gdb.aarch64.fpu' feature is optional. If present, it
|
||
should contain registers 'v0' through 'v31', 'fpsr', and 'fpcr'.
|
||
|
||
The 'org.gnu.gdb.aarch64.sve' feature is optional. If present, it
|
||
should contain registers 'z0' through 'z31', 'p0' through 'p15', 'ffr'
|
||
and 'vg'.
|
||
|
||
The 'org.gnu.gdb.aarch64.pauth' feature is optional. If present, it
|
||
should contain registers 'pauth_dmask' and 'pauth_cmask'.
|
||
|
||
|
||
File: gdb.info, Node: ARC Features, Next: ARM Features, Prev: AArch64 Features, Up: Standard Target Features
|
||
|
||
G.5.2 ARC Features
|
||
------------------
|
||
|
||
ARC processors are highly configurable, so even core registers and their
|
||
number are not completely predetermined. In addition flags and PC
|
||
registers which are important to GDB are not "core" registers in ARC. It
|
||
is required that one of the core registers features is present.
|
||
'org.gnu.gdb.arc.aux-minimal' feature is mandatory.
|
||
|
||
The 'org.gnu.gdb.arc.core.v2' feature is required for ARC EM and ARC
|
||
HS targets with a normal register file. It should contain registers
|
||
'r0' through 'r25', 'gp', 'fp', 'sp', 'r30', 'blink', 'lp_count' and
|
||
'pcl'. This feature may contain register 'ilink' and any of extension
|
||
core registers 'r32' through 'r59/acch'. 'ilink' and extension core
|
||
registers are not available to read/write, when debugging GNU/Linux
|
||
applications, thus 'ilink' is made optional.
|
||
|
||
The 'org.gnu.gdb.arc.core-reduced.v2' feature is required for ARC EM
|
||
and ARC HS targets with a reduced register file. It should contain
|
||
registers 'r0' through 'r3', 'r10' through 'r15', 'gp', 'fp', 'sp',
|
||
'r30', 'blink', 'lp_count' and 'pcl'. This feature may contain register
|
||
'ilink' and any of extension core registers 'r32' through 'r59/acch'.
|
||
|
||
The 'org.gnu.gdb.arc.core.arcompact' feature is required for
|
||
ARCompact targets with a normal register file. It should contain
|
||
registers 'r0' through 'r25', 'gp', 'fp', 'sp', 'r30', 'blink',
|
||
'lp_count' and 'pcl'. This feature may contain registers 'ilink1',
|
||
'ilink2' and any of extension core registers 'r32' through 'r59/acch'.
|
||
'ilink1' and 'ilink2' and extension core registers are not available
|
||
when debugging GNU/Linux applications. The only difference with
|
||
'org.gnu.gdb.arc.core.v2' feature is in the names of 'ilink1' and
|
||
'ilink2' registers and that 'r30' is mandatory in ARC v2, but 'ilink2'
|
||
is optional on ARCompact.
|
||
|
||
The 'org.gnu.gdb.arc.aux-minimal' feature is required for all ARC
|
||
targets. It should contain registers 'pc' and 'status32'.
|
||
|
||
|
||
File: gdb.info, Node: ARM Features, Next: i386 Features, Prev: ARC Features, Up: Standard Target Features
|
||
|
||
G.5.3 ARM Features
|
||
------------------
|
||
|
||
The 'org.gnu.gdb.arm.core' feature is required for non-M-profile ARM
|
||
targets. It should contain registers 'r0' through 'r13', 'sp', 'lr',
|
||
'pc', and 'cpsr'.
|
||
|
||
For M-profile targets (e.g. Cortex-M3), the 'org.gnu.gdb.arm.core'
|
||
feature is replaced by 'org.gnu.gdb.arm.m-profile'. It should contain
|
||
registers 'r0' through 'r13', 'sp', 'lr', 'pc', and 'xpsr'.
|
||
|
||
The 'org.gnu.gdb.arm.fpa' feature is optional. If present, it should
|
||
contain registers 'f0' through 'f7' and 'fps'.
|
||
|
||
The 'org.gnu.gdb.xscale.iwmmxt' feature is optional. If present, it
|
||
should contain at least registers 'wR0' through 'wR15' and 'wCGR0'
|
||
through 'wCGR3'. The 'wCID', 'wCon', 'wCSSF', and 'wCASF' registers are
|
||
optional.
|
||
|
||
The 'org.gnu.gdb.arm.vfp' feature is optional. If present, it should
|
||
contain at least registers 'd0' through 'd15'. If they are present,
|
||
'd16' through 'd31' should also be included. GDB will synthesize the
|
||
single-precision registers from halves of the double-precision
|
||
registers.
|
||
|
||
The 'org.gnu.gdb.arm.neon' feature is optional. It does not need to
|
||
contain registers; it instructs GDB to display the VFP double-precision
|
||
registers as vectors and to synthesize the quad-precision registers from
|
||
pairs of double-precision registers. If this feature is present,
|
||
'org.gnu.gdb.arm.vfp' must also be present and include 32
|
||
double-precision registers.
|
||
|
||
|
||
File: gdb.info, Node: i386 Features, Next: MicroBlaze Features, Prev: ARM Features, Up: Standard Target Features
|
||
|
||
G.5.4 i386 Features
|
||
-------------------
|
||
|
||
The 'org.gnu.gdb.i386.core' feature is required for i386/amd64 targets.
|
||
It should describe the following registers:
|
||
|
||
- 'eax' through 'edi' plus 'eip' for i386
|
||
- 'rax' through 'r15' plus 'rip' for amd64
|
||
- 'eflags', 'cs', 'ss', 'ds', 'es', 'fs', 'gs'
|
||
- 'st0' through 'st7'
|
||
- 'fctrl', 'fstat', 'ftag', 'fiseg', 'fioff', 'foseg', 'fooff' and
|
||
'fop'
|
||
|
||
The register sets may be different, depending on the target.
|
||
|
||
The 'org.gnu.gdb.i386.sse' feature is optional. It should describe
|
||
registers:
|
||
|
||
- 'xmm0' through 'xmm7' for i386
|
||
- 'xmm0' through 'xmm15' for amd64
|
||
- 'mxcsr'
|
||
|
||
The 'org.gnu.gdb.i386.avx' feature is optional and requires the
|
||
'org.gnu.gdb.i386.sse' feature. It should describe the upper 128 bits
|
||
of YMM registers:
|
||
|
||
- 'ymm0h' through 'ymm7h' for i386
|
||
- 'ymm0h' through 'ymm15h' for amd64
|
||
|
||
The 'org.gnu.gdb.i386.mpx' is an optional feature representing Intel
|
||
Memory Protection Extension (MPX). It should describe the following
|
||
registers:
|
||
|
||
- 'bnd0raw' through 'bnd3raw' for i386 and amd64.
|
||
- 'bndcfgu' and 'bndstatus' for i386 and amd64.
|
||
|
||
The 'org.gnu.gdb.i386.linux' feature is optional. It should describe
|
||
a single register, 'orig_eax'.
|
||
|
||
The 'org.gnu.gdb.i386.segments' feature is optional. It should
|
||
describe two system registers: 'fs_base' and 'gs_base'.
|
||
|
||
The 'org.gnu.gdb.i386.avx512' feature is optional and requires the
|
||
'org.gnu.gdb.i386.avx' feature. It should describe additional XMM
|
||
registers:
|
||
|
||
- 'xmm16h' through 'xmm31h', only valid for amd64.
|
||
|
||
It should describe the upper 128 bits of additional YMM registers:
|
||
|
||
- 'ymm16h' through 'ymm31h', only valid for amd64.
|
||
|
||
It should describe the upper 256 bits of ZMM registers:
|
||
|
||
- 'zmm0h' through 'zmm7h' for i386.
|
||
- 'zmm0h' through 'zmm15h' for amd64.
|
||
|
||
It should describe the additional ZMM registers:
|
||
|
||
- 'zmm16h' through 'zmm31h', only valid for amd64.
|
||
|
||
The 'org.gnu.gdb.i386.pkeys' feature is optional. It should describe
|
||
a single register, 'pkru'. It is a 32-bit register valid for i386 and
|
||
amd64.
|
||
|
||
|
||
File: gdb.info, Node: MicroBlaze Features, Next: MIPS Features, Prev: i386 Features, Up: Standard Target Features
|
||
|
||
G.5.5 MicroBlaze Features
|
||
-------------------------
|
||
|
||
The 'org.gnu.gdb.microblaze.core' feature is required for MicroBlaze
|
||
targets. It should contain registers 'r0' through 'r31', 'rpc', 'rmsr',
|
||
'rear', 'resr', 'rfsr', 'rbtr', 'rpvr', 'rpvr1' through 'rpvr11',
|
||
'redr', 'rpid', 'rzpr', 'rtlbx', 'rtlbsx', 'rtlblo', and 'rtlbhi'.
|
||
|
||
The 'org.gnu.gdb.microblaze.stack-protect' feature is optional. If
|
||
present, it should contain registers 'rshr' and 'rslr'
|
||
|
||
|
||
File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: MicroBlaze Features, Up: Standard Target Features
|
||
|
||
G.5.6 MIPS Features
|
||
-------------------
|
||
|
||
The 'org.gnu.gdb.mips.cpu' feature is required for MIPS targets. It
|
||
should contain registers 'r0' through 'r31', 'lo', 'hi', and 'pc'. They
|
||
may be 32-bit or 64-bit depending on the target.
|
||
|
||
The 'org.gnu.gdb.mips.cp0' feature is also required. It should
|
||
contain at least the 'status', 'badvaddr', and 'cause' registers. They
|
||
may be 32-bit or 64-bit depending on the target.
|
||
|
||
The 'org.gnu.gdb.mips.fpu' feature is currently required, though it
|
||
may be optional in a future version of GDB. It should contain registers
|
||
'f0' through 'f31', 'fcsr', and 'fir'. They may be 32-bit or 64-bit
|
||
depending on the target.
|
||
|
||
The 'org.gnu.gdb.mips.dsp' feature is optional. It should contain
|
||
registers 'hi1' through 'hi3', 'lo1' through 'lo3', and 'dspctl'. The
|
||
'dspctl' register should be 32-bit and the rest may be 32-bit or 64-bit
|
||
depending on the target.
|
||
|
||
The 'org.gnu.gdb.mips.linux' feature is optional. It should contain
|
||
a single register, 'restart', which is used by the Linux kernel to
|
||
control restartable syscalls.
|
||
|
||
|
||
File: gdb.info, Node: M68K Features, Next: NDS32 Features, Prev: MIPS Features, Up: Standard Target Features
|
||
|
||
G.5.7 M68K Features
|
||
-------------------
|
||
|
||
''org.gnu.gdb.m68k.core''
|
||
''org.gnu.gdb.coldfire.core''
|
||
''org.gnu.gdb.fido.core''
|
||
One of those features must be always present. The feature that is
|
||
present determines which flavor of m68k is used. The feature that
|
||
is present should contain registers 'd0' through 'd7', 'a0' through
|
||
'a5', 'fp', 'sp', 'ps' and 'pc'.
|
||
|
||
''org.gnu.gdb.coldfire.fp''
|
||
This feature is optional. If present, it should contain registers
|
||
'fp0' through 'fp7', 'fpcontrol', 'fpstatus' and 'fpiaddr'.
|
||
|
||
|
||
File: gdb.info, Node: NDS32 Features, Next: Nios II Features, Prev: M68K Features, Up: Standard Target Features
|
||
|
||
G.5.8 NDS32 Features
|
||
--------------------
|
||
|
||
The 'org.gnu.gdb.nds32.core' feature is required for NDS32 targets. It
|
||
should contain at least registers 'r0' through 'r10', 'r15', 'fp', 'gp',
|
||
'lp', 'sp', and 'pc'.
|
||
|
||
The 'org.gnu.gdb.nds32.fpu' feature is optional. If present, it
|
||
should contain 64-bit double-precision floating-point registers 'fd0'
|
||
through _fdN_, which should be 'fd3', 'fd7', 'fd15', or 'fd31' based on
|
||
the FPU configuration implemented.
|
||
|
||
_Note:_ The first sixteen 64-bit double-precision floating-point
|
||
registers are overlapped with the thirty-two 32-bit single-precision
|
||
floating-point registers. The 32-bit single-precision registers, if not
|
||
being listed explicitly, will be synthesized from halves of the
|
||
overlapping 64-bit double-precision registers. Listing 32-bit
|
||
single-precision registers explicitly is deprecated, and the support to
|
||
it could be totally removed some day.
|
||
|
||
|
||
File: gdb.info, Node: Nios II Features, Next: OpenRISC 1000 Features, Prev: NDS32 Features, Up: Standard Target Features
|
||
|
||
G.5.9 Nios II Features
|
||
----------------------
|
||
|
||
The 'org.gnu.gdb.nios2.cpu' feature is required for Nios II targets. It
|
||
should contain the 32 core registers ('zero', 'at', 'r2' through 'r23',
|
||
'et' through 'ra'), 'pc', and the 16 control registers ('status' through
|
||
'mpuacc').
|
||
|
||
|
||
File: gdb.info, Node: OpenRISC 1000 Features, Next: PowerPC Features, Prev: Nios II Features, Up: Standard Target Features
|
||
|
||
G.5.10 Openrisc 1000 Features
|
||
-----------------------------
|
||
|
||
The 'org.gnu.gdb.or1k.group0' feature is required for OpenRISC 1000
|
||
targets. It should contain the 32 general purpose registers ('r0'
|
||
through 'r31'), 'ppc', 'npc' and 'sr'.
|
||
|
||
|
||
File: gdb.info, Node: PowerPC Features, Next: RISC-V Features, Prev: OpenRISC 1000 Features, Up: Standard Target Features
|
||
|
||
G.5.11 PowerPC Features
|
||
-----------------------
|
||
|
||
The 'org.gnu.gdb.power.core' feature is required for PowerPC targets.
|
||
It should contain registers 'r0' through 'r31', 'pc', 'msr', 'cr', 'lr',
|
||
'ctr', and 'xer'. They may be 32-bit or 64-bit depending on the target.
|
||
|
||
The 'org.gnu.gdb.power.fpu' feature is optional. It should contain
|
||
registers 'f0' through 'f31' and 'fpscr'.
|
||
|
||
The 'org.gnu.gdb.power.altivec' feature is optional. It should
|
||
contain registers 'vr0' through 'vr31', 'vscr', and 'vrsave'. GDB will
|
||
define pseudo-registers 'v0' through 'v31' as aliases for the
|
||
corresponding 'vrX' registers.
|
||
|
||
The 'org.gnu.gdb.power.vsx' feature is optional. It should contain
|
||
registers 'vs0h' through 'vs31h'. GDB will combine these registers with
|
||
the floating point registers ('f0' through 'f31') and the altivec
|
||
registers ('vr0' through 'vr31') to present the 128-bit wide registers
|
||
'vs0' through 'vs63', the set of vector-scalar registers for POWER7.
|
||
Therefore, this feature requires both 'org.gnu.gdb.power.fpu' and
|
||
'org.gnu.gdb.power.altivec'.
|
||
|
||
The 'org.gnu.gdb.power.spe' feature is optional. It should contain
|
||
registers 'ev0h' through 'ev31h', 'acc', and 'spefscr'. SPE targets
|
||
should provide 32-bit registers in 'org.gnu.gdb.power.core' and provide
|
||
the upper halves in 'ev0h' through 'ev31h'. GDB will combine these to
|
||
present registers 'ev0' through 'ev31' to the user.
|
||
|
||
The 'org.gnu.gdb.power.ppr' feature is optional. It should contain
|
||
the 64-bit register 'ppr'.
|
||
|
||
The 'org.gnu.gdb.power.dscr' feature is optional. It should contain
|
||
the 64-bit register 'dscr'.
|
||
|
||
The 'org.gnu.gdb.power.tar' feature is optional. It should contain
|
||
the 64-bit register 'tar'.
|
||
|
||
The 'org.gnu.gdb.power.ebb' feature is optional. It should contain
|
||
registers 'bescr', 'ebbhr' and 'ebbrr', all 64-bit wide.
|
||
|
||
The 'org.gnu.gdb.power.linux.pmu' feature is optional. It should
|
||
contain registers 'mmcr0', 'mmcr2', 'siar', 'sdar' and 'sier', all
|
||
64-bit wide. This is the subset of the isa 2.07 server PMU registers
|
||
provided by GNU/Linux.
|
||
|
||
The 'org.gnu.gdb.power.htm.spr' feature is optional. It should
|
||
contain registers 'tfhar', 'texasr' and 'tfiar', all 64-bit wide.
|
||
|
||
The 'org.gnu.gdb.power.htm.core' feature is optional. It should
|
||
contain the checkpointed general-purpose registers 'cr0' through 'cr31',
|
||
as well as the checkpointed registers 'clr' and 'cctr'. These registers
|
||
may all be either 32-bit or 64-bit depending on the target. It should
|
||
also contain the checkpointed registers 'ccr' and 'cxer', which should
|
||
both be 32-bit wide.
|
||
|
||
The 'org.gnu.gdb.power.htm.fpu' feature is optional. It should
|
||
contain the checkpointed 64-bit floating-point registers 'cf0' through
|
||
'cf31', as well as the checkpointed 64-bit register 'cfpscr'.
|
||
|
||
The 'org.gnu.gdb.power.htm.altivec' feature is optional. It should
|
||
contain the checkpointed altivec registers 'cvr0' through 'cvr31', all
|
||
128-bit wide. It should also contain the checkpointed registers 'cvscr'
|
||
and 'cvrsave', both 32-bit wide.
|
||
|
||
The 'org.gnu.gdb.power.htm.vsx' feature is optional. It should
|
||
contain registers 'cvs0h' through 'cvs31h'. GDB will combine these
|
||
registers with the checkpointed floating point registers ('cf0' through
|
||
'cf31') and the checkpointed altivec registers ('cvr0' through 'cvr31')
|
||
to present the 128-bit wide checkpointed vector-scalar registers 'cvs0'
|
||
through 'cvs63'. Therefore, this feature requires both
|
||
'org.gnu.gdb.power.htm.altivec' and 'org.gnu.gdb.power.htm.fpu'.
|
||
|
||
The 'org.gnu.gdb.power.htm.ppr' feature is optional. It should
|
||
contain the 64-bit checkpointed register 'cppr'.
|
||
|
||
The 'org.gnu.gdb.power.htm.dscr' feature is optional. It should
|
||
contain the 64-bit checkpointed register 'cdscr'.
|
||
|
||
The 'org.gnu.gdb.power.htm.tar' feature is optional. It should
|
||
contain the 64-bit checkpointed register 'ctar'.
|
||
|
||
|
||
File: gdb.info, Node: RISC-V Features, Next: RX Features, Prev: PowerPC Features, Up: Standard Target Features
|
||
|
||
G.5.12 RISC-V Features
|
||
----------------------
|
||
|
||
The 'org.gnu.gdb.riscv.cpu' feature is required for RISC-V targets. It
|
||
should contain the registers 'x0' through 'x31', and 'pc'. Either the
|
||
architectural names ('x0', 'x1', etc) can be used, or the ABI names
|
||
('zero', 'ra', etc).
|
||
|
||
The 'org.gnu.gdb.riscv.fpu' feature is optional. If present, it
|
||
should contain registers 'f0' through 'f31', 'fflags', 'frm', and
|
||
'fcsr'. As with the cpu feature, either the architectural register
|
||
names, or the ABI names can be used.
|
||
|
||
The 'org.gnu.gdb.riscv.virtual' feature is optional. If present, it
|
||
should contain registers that are not backed by real registers on the
|
||
target, but are instead virtual, where the register value is derived
|
||
from other target state. In many ways these are like GDBs
|
||
pseudo-registers, except implemented by the target. Currently the only
|
||
register expected in this set is the one byte 'priv' register that
|
||
contains the target's privilege level in the least significant two bits.
|
||
|
||
The 'org.gnu.gdb.riscv.csr' feature is optional. If present, it
|
||
should contain all of the target's standard CSRs. Standard CSRs are
|
||
those defined in the RISC-V specification documents. There is some
|
||
overlap between this feature and the fpu feature; the 'fflags', 'frm',
|
||
and 'fcsr' registers could be in either feature. The expectation is
|
||
that these registers will be in the fpu feature if the target has
|
||
floating point hardware, but can be moved into the csr feature if the
|
||
target has the floating point control registers, but no other floating
|
||
point hardware.
|
||
|
||
|
||
File: gdb.info, Node: RX Features, Next: S/390 and System z Features, Prev: RISC-V Features, Up: Standard Target Features
|
||
|
||
G.5.13 RX Features
|
||
------------------
|
||
|
||
The 'org.gnu.gdb.rx.core' feature is required for RX targets. It should
|
||
contain the registers 'r0' through 'r15', 'usp', 'isp', 'psw', 'pc',
|
||
'intb', 'bpsw', 'bpc', 'fintv', 'fpsw', and 'acc'.
|
||
|
||
|
||
File: gdb.info, Node: S/390 and System z Features, Next: Sparc Features, Prev: RX Features, Up: Standard Target Features
|
||
|
||
G.5.14 S/390 and System z Features
|
||
----------------------------------
|
||
|
||
The 'org.gnu.gdb.s390.core' feature is required for S/390 and System z
|
||
targets. It should contain the PSW and the 16 general registers. In
|
||
particular, System z targets should provide the 64-bit registers 'pswm',
|
||
'pswa', and 'r0' through 'r15'. S/390 targets should provide the 32-bit
|
||
versions of these registers. A System z target that runs in 31-bit
|
||
addressing mode should provide 32-bit versions of 'pswm' and 'pswa', as
|
||
well as the general register's upper halves 'r0h' through 'r15h', and
|
||
their lower halves 'r0l' through 'r15l'.
|
||
|
||
The 'org.gnu.gdb.s390.fpr' feature is required. It should contain
|
||
the 64-bit registers 'f0' through 'f15', and 'fpc'.
|
||
|
||
The 'org.gnu.gdb.s390.acr' feature is required. It should contain
|
||
the 32-bit registers 'acr0' through 'acr15'.
|
||
|
||
The 'org.gnu.gdb.s390.linux' feature is optional. It should contain
|
||
the register 'orig_r2', which is 64-bit wide on System z targets and
|
||
32-bit otherwise. In addition, the feature may contain the 'last_break'
|
||
register, whose width depends on the addressing mode, as well as the
|
||
'system_call' register, which is always 32-bit wide.
|
||
|
||
The 'org.gnu.gdb.s390.tdb' feature is optional. It should contain
|
||
the 64-bit registers 'tdb0', 'tac', 'tct', 'atia', and 'tr0' through
|
||
'tr15'.
|
||
|
||
The 'org.gnu.gdb.s390.vx' feature is optional. It should contain
|
||
64-bit wide registers 'v0l' through 'v15l', which will be combined by
|
||
GDB with the floating point registers 'f0' through 'f15' to present the
|
||
128-bit wide vector registers 'v0' through 'v15'. In addition, this
|
||
feature should contain the 128-bit wide vector registers 'v16' through
|
||
'v31'.
|
||
|
||
The 'org.gnu.gdb.s390.gs' feature is optional. It should contain the
|
||
64-bit wide guarded-storage-control registers 'gsd', 'gssm', and
|
||
'gsepla'.
|
||
|
||
The 'org.gnu.gdb.s390.gsbc' feature is optional. It should contain
|
||
the 64-bit wide guarded-storage broadcast control registers 'bc_gsd',
|
||
'bc_gssm', and 'bc_gsepla'.
|
||
|
||
|
||
File: gdb.info, Node: Sparc Features, Next: TIC6x Features, Prev: S/390 and System z Features, Up: Standard Target Features
|
||
|
||
G.5.15 Sparc Features
|
||
---------------------
|
||
|
||
The 'org.gnu.gdb.sparc.cpu' feature is required for sparc32/sparc64
|
||
targets. It should describe the following registers:
|
||
|
||
- 'g0' through 'g7'
|
||
- 'o0' through 'o7'
|
||
- 'l0' through 'l7'
|
||
- 'i0' through 'i7'
|
||
|
||
They may be 32-bit or 64-bit depending on the target.
|
||
|
||
Also the 'org.gnu.gdb.sparc.fpu' feature is required for
|
||
sparc32/sparc64 targets. It should describe the following registers:
|
||
|
||
- 'f0' through 'f31'
|
||
- 'f32' through 'f62' for sparc64
|
||
|
||
The 'org.gnu.gdb.sparc.cp0' feature is required for sparc32/sparc64
|
||
targets. It should describe the following registers:
|
||
|
||
- 'y', 'psr', 'wim', 'tbr', 'pc', 'npc', 'fsr', and 'csr' for sparc32
|
||
- 'pc', 'npc', 'state', 'fsr', 'fprs', and 'y' for sparc64
|
||
|
||
|
||
File: gdb.info, Node: TIC6x Features, Prev: Sparc Features, Up: Standard Target Features
|
||
|
||
G.5.16 TMS320C6x Features
|
||
-------------------------
|
||
|
||
The 'org.gnu.gdb.tic6x.core' feature is required for TMS320C6x targets.
|
||
It should contain registers 'A0' through 'A15', registers 'B0' through
|
||
'B15', 'CSR' and 'PC'.
|
||
|
||
The 'org.gnu.gdb.tic6x.gp' feature is optional. It should contain
|
||
registers 'A16' through 'A31' and 'B16' through 'B31'.
|
||
|
||
The 'org.gnu.gdb.tic6x.c6xp' feature is optional. It should contain
|
||
registers 'TSR', 'ILC' and 'RILC'.
|
||
|
||
|
||
File: gdb.info, Node: Operating System Information, Next: Trace File Format, Prev: Target Descriptions, Up: Top
|
||
|
||
Appendix H Operating System Information
|
||
***************************************
|
||
|
||
* Menu:
|
||
|
||
* Process list::
|
||
|
||
Users of GDB often wish to obtain information about the state of the
|
||
operating system running on the target--for example the list of
|
||
processes, or the list of open files. This section describes the
|
||
mechanism that makes it possible. This mechanism is similar to the
|
||
target features mechanism (*note Target Descriptions::), but focuses on
|
||
a different aspect of target.
|
||
|
||
Operating system information is retrieved from the target via the
|
||
remote protocol, using 'qXfer' requests (*note qXfer osdata read::).
|
||
The object name in the request should be 'osdata', and the ANNEX
|
||
identifies the data to be fetched.
|
||
|
||
|
||
File: gdb.info, Node: Process list, Up: Operating System Information
|
||
|
||
H.1 Process list
|
||
================
|
||
|
||
When requesting the process list, the ANNEX field in the 'qXfer' request
|
||
should be 'processes'. The returned data is an XML document. The
|
||
formal syntax of this document is defined in 'gdb/features/osdata.dtd'.
|
||
|
||
An example document is:
|
||
|
||
<?xml version="1.0"?>
|
||
<!DOCTYPE target SYSTEM "osdata.dtd">
|
||
<osdata type="processes">
|
||
<item>
|
||
<column name="pid">1</column>
|
||
<column name="user">root</column>
|
||
<column name="command">/sbin/init</column>
|
||
<column name="cores">1,2,3</column>
|
||
</item>
|
||
</osdata>
|
||
|
||
Each item should include a column whose name is 'pid'. The value of
|
||
that column should identify the process on the target. The 'user' and
|
||
'command' columns are optional, and will be displayed by GDB. The
|
||
'cores' column, if present, should contain a comma-separated list of
|
||
cores that this process is running on. Target may provide additional
|
||
columns, which GDB currently ignores.
|
||
|
||
|
||
File: gdb.info, Node: Trace File Format, Next: Index Section Format, Prev: Operating System Information, Up: Top
|
||
|
||
Appendix I Trace File Format
|
||
****************************
|
||
|
||
The trace file comes in three parts: a header, a textual description
|
||
section, and a trace frame section with binary data.
|
||
|
||
The header has the form '\x7fTRACE0\n'. The first byte is '0x7f' so
|
||
as to indicate that the file contains binary data, while the '0' is a
|
||
version number that may have different values in the future.
|
||
|
||
The description section consists of multiple lines of ASCII text
|
||
separated by newline characters ('0xa'). The lines may include a
|
||
variety of optional descriptive or context-setting information, such as
|
||
tracepoint definitions or register set size. GDB will ignore any line
|
||
that it does not recognize. An empty line marks the end of this
|
||
section.
|
||
|
||
'R SIZE'
|
||
Specifies the size of a register block in bytes. This is equal to
|
||
the size of a 'g' packet payload in the remote protocol. SIZE is
|
||
an ascii decimal number. There should be only one such line in a
|
||
single trace file.
|
||
|
||
'status STATUS'
|
||
Trace status. STATUS has the same format as a 'qTStatus' remote
|
||
packet reply. There should be only one such line in a single trace
|
||
file.
|
||
|
||
'tp PAYLOAD'
|
||
Tracepoint definition. The PAYLOAD has the same format as
|
||
'qTfP'/'qTsP' remote packet reply payload. A single tracepoint may
|
||
take multiple lines of definition, corresponding to the multiple
|
||
reply packets.
|
||
|
||
'tsv PAYLOAD'
|
||
Trace state variable definition. The PAYLOAD has the same format
|
||
as 'qTfV'/'qTsV' remote packet reply payload. A single variable
|
||
may take multiple lines of definition, corresponding to the
|
||
multiple reply packets.
|
||
|
||
'tdesc PAYLOAD'
|
||
Target description in XML format. The PAYLOAD is a single line of
|
||
the XML file. All such lines should be concatenated together to
|
||
get the original XML file. This file is in the same format as
|
||
'qXfer' 'features' payload, and corresponds to the main
|
||
'target.xml' file. Includes are not allowed.
|
||
|
||
The trace frame section consists of a number of consecutive frames.
|
||
Each frame begins with a two-byte tracepoint number, followed by a
|
||
four-byte size giving the amount of data in the frame. The data in the
|
||
frame consists of a number of blocks, each introduced by a character
|
||
indicating its type (at least register, memory, and trace state
|
||
variable). The data in this section is raw binary, not a hexadecimal or
|
||
other encoding; its endianness matches the target's endianness.
|
||
|
||
'R BYTES'
|
||
Register block. The number and ordering of bytes matches that of a
|
||
'g' packet in the remote protocol. Note that these are the actual
|
||
bytes, in target order, not a hexadecimal encoding.
|
||
|
||
'M ADDRESS LENGTH BYTES...'
|
||
Memory block. This is a contiguous block of memory, at the 8-byte
|
||
address ADDRESS, with a 2-byte length LENGTH, followed by LENGTH
|
||
bytes.
|
||
|
||
'V NUMBER VALUE'
|
||
Trace state variable block. This records the 8-byte signed value
|
||
VALUE of trace state variable numbered NUMBER.
|
||
|
||
Future enhancements of the trace file format may include additional
|
||
types of blocks.
|
||
|
||
|
||
File: gdb.info, Node: Index Section Format, Next: Man Pages, Prev: Trace File Format, Up: Top
|
||
|
||
Appendix J '.gdb_index' section format
|
||
**************************************
|
||
|
||
This section documents the index section that is created by 'save
|
||
gdb-index' (*note Index Files::). The index section is DWARF-specific;
|
||
some knowledge of DWARF is assumed in this description.
|
||
|
||
The mapped index file format is designed to be directly 'mmap'able on
|
||
any architecture. In most cases, a datum is represented using a
|
||
little-endian 32-bit integer value, called an 'offset_type'. Big endian
|
||
machines must byte-swap the values before using them. Exceptions to
|
||
this rule are noted. The data is laid out such that alignment is always
|
||
respected.
|
||
|
||
A mapped index consists of several areas, laid out in order.
|
||
|
||
1. The file header. This is a sequence of values, of 'offset_type'
|
||
unless otherwise noted:
|
||
|
||
1. The version number, currently 8. Versions 1, 2 and 3 are
|
||
obsolete. Version 4 uses a different hashing function from
|
||
versions 5 and 6. Version 6 includes symbols for inlined
|
||
functions, whereas versions 4 and 5 do not. Version 7 adds
|
||
attributes to the CU indices in the symbol table. Version 8
|
||
specifies that symbols from DWARF type units
|
||
('DW_TAG_type_unit') refer to the type unit's symbol table and
|
||
not the compilation unit ('DW_TAG_comp_unit') using the type.
|
||
|
||
GDB will only read version 4, 5, or 6 indices by specifying
|
||
'set use-deprecated-index-sections on'. GDB has a workaround
|
||
for potentially broken version 7 indices so it is currently
|
||
not flagged as deprecated.
|
||
|
||
2. The offset, from the start of the file, of the CU list.
|
||
|
||
3. The offset, from the start of the file, of the types CU list.
|
||
Note that this area can be empty, in which case this offset
|
||
will be equal to the next offset.
|
||
|
||
4. The offset, from the start of the file, of the address area.
|
||
|
||
5. The offset, from the start of the file, of the symbol table.
|
||
|
||
6. The offset, from the start of the file, of the constant pool.
|
||
|
||
2. The CU list. This is a sequence of pairs of 64-bit little-endian
|
||
values, sorted by the CU offset. The first element in each pair is
|
||
the offset of a CU in the '.debug_info' section. The second
|
||
element in each pair is the length of that CU. References to a CU
|
||
elsewhere in the map are done using a CU index, which is just the
|
||
0-based index into this table. Note that if there are type CUs,
|
||
then conceptually CUs and type CUs form a single list for the
|
||
purposes of CU indices.
|
||
|
||
3. The types CU list. This is a sequence of triplets of 64-bit
|
||
little-endian values. In a triplet, the first value is the CU
|
||
offset, the second value is the type offset in the CU, and the
|
||
third value is the type signature. The types CU list is not
|
||
sorted.
|
||
|
||
4. The address area. The address area consists of a sequence of
|
||
address entries. Each address entry has three elements:
|
||
|
||
1. The low address. This is a 64-bit little-endian value.
|
||
|
||
2. The high address. This is a 64-bit little-endian value. Like
|
||
'DW_AT_high_pc', the value is one byte beyond the end.
|
||
|
||
3. The CU index. This is an 'offset_type' value.
|
||
|
||
5. The symbol table. This is an open-addressed hash table. The size
|
||
of the hash table is always a power of 2.
|
||
|
||
Each slot in the hash table consists of a pair of 'offset_type'
|
||
values. The first value is the offset of the symbol's name in the
|
||
constant pool. The second value is the offset of the CU vector in
|
||
the constant pool.
|
||
|
||
If both values are 0, then this slot in the hash table is empty.
|
||
This is ok because while 0 is a valid constant pool index, it
|
||
cannot be a valid index for both a string and a CU vector.
|
||
|
||
The hash value for a table entry is computed by applying an
|
||
iterative hash function to the symbol's name. Starting with an
|
||
initial value of 'r = 0', each (unsigned) character 'c' in the
|
||
string is incorporated into the hash using the formula depending on
|
||
the index version:
|
||
|
||
Version 4
|
||
The formula is 'r = r * 67 + c - 113'.
|
||
|
||
Versions 5 to 7
|
||
The formula is 'r = r * 67 + tolower (c) - 113'.
|
||
|
||
The terminating '\0' is not incorporated into the hash.
|
||
|
||
The step size used in the hash table is computed via '((hash * 17)
|
||
& (size - 1)) | 1', where 'hash' is the hash value, and 'size' is
|
||
the size of the hash table. The step size is used to find the next
|
||
candidate slot when handling a hash collision.
|
||
|
||
The names of C++ symbols in the hash table are canonicalized. We
|
||
don't currently have a simple description of the canonicalization
|
||
algorithm; if you intend to create new index sections, you must
|
||
read the code.
|
||
|
||
6. The constant pool. This is simply a bunch of bytes. It is
|
||
organized so that alignment is correct: CU vectors are stored
|
||
first, followed by strings.
|
||
|
||
A CU vector in the constant pool is a sequence of 'offset_type'
|
||
values. The first value is the number of CU indices in the vector.
|
||
Each subsequent value is the index and symbol attributes of a CU in
|
||
the CU list. This element in the hash table is used to indicate
|
||
which CUs define the symbol and how the symbol is used. See below
|
||
for the format of each CU index+attributes entry.
|
||
|
||
A string in the constant pool is zero-terminated.
|
||
|
||
Attributes were added to CU index values in '.gdb_index' version 7.
|
||
If a symbol has multiple uses within a CU then there is one CU
|
||
index+attributes value for each use.
|
||
|
||
The format of each CU index+attributes entry is as follows (bit 0 =
|
||
LSB):
|
||
|
||
Bits 0-23
|
||
This is the index of the CU in the CU list.
|
||
Bits 24-27
|
||
These bits are reserved for future purposes and must be zero.
|
||
Bits 28-30
|
||
The kind of the symbol in the CU.
|
||
|
||
0
|
||
This value is reserved and should not be used. By reserving
|
||
zero the full 'offset_type' value is backwards compatible with
|
||
previous versions of the index.
|
||
1
|
||
The symbol is a type.
|
||
2
|
||
The symbol is a variable or an enum value.
|
||
3
|
||
The symbol is a function.
|
||
4
|
||
Any other kind of symbol.
|
||
5,6,7
|
||
These values are reserved.
|
||
|
||
Bit 31
|
||
This bit is zero if the value is global and one if it is static.
|
||
|
||
The determination of whether a symbol is global or static is
|
||
complicated. The authorative reference is the file 'dwarf2read.c'
|
||
in GDB sources.
|
||
|
||
This pseudo-code describes the computation of a symbol's kind and
|
||
global/static attributes in the index.
|
||
|
||
is_external = get_attribute (die, DW_AT_external);
|
||
language = get_attribute (cu_die, DW_AT_language);
|
||
switch (die->tag)
|
||
{
|
||
case DW_TAG_typedef:
|
||
case DW_TAG_base_type:
|
||
case DW_TAG_subrange_type:
|
||
kind = TYPE;
|
||
is_static = 1;
|
||
break;
|
||
case DW_TAG_enumerator:
|
||
kind = VARIABLE;
|
||
is_static = language != CPLUS;
|
||
break;
|
||
case DW_TAG_subprogram:
|
||
kind = FUNCTION;
|
||
is_static = ! (is_external || language == ADA);
|
||
break;
|
||
case DW_TAG_constant:
|
||
kind = VARIABLE;
|
||
is_static = ! is_external;
|
||
break;
|
||
case DW_TAG_variable:
|
||
kind = VARIABLE;
|
||
is_static = ! is_external;
|
||
break;
|
||
case DW_TAG_namespace:
|
||
kind = TYPE;
|
||
is_static = 0;
|
||
break;
|
||
case DW_TAG_class_type:
|
||
case DW_TAG_interface_type:
|
||
case DW_TAG_structure_type:
|
||
case DW_TAG_union_type:
|
||
case DW_TAG_enumeration_type:
|
||
kind = TYPE;
|
||
is_static = language != CPLUS;
|
||
break;
|
||
default:
|
||
assert (0);
|
||
}
|
||
|
||
|
||
File: gdb.info, Node: Man Pages, Next: Copying, Prev: Index Section Format, Up: Top
|
||
|
||
Appendix K Manual pages
|
||
***********************
|
||
|
||
* Menu:
|
||
|
||
* gdb man:: The GNU Debugger man page
|
||
* gdbserver man:: Remote Server for the GNU Debugger man page
|
||
* gcore man:: Generate a core file of a running program
|
||
* gdbinit man:: gdbinit scripts
|
||
* gdb-add-index man:: Add index files to speed up GDB
|
||
|
||
|
||
File: gdb.info, Node: gdb man, Next: gdbserver man, Up: Man Pages
|
||
|
||
gdb man
|
||
=======
|
||
|
||
gdb ['-help'] ['-nh'] ['-nx'] ['-q'] ['-batch'] ['-cd='DIR] ['-f']
|
||
['-b' BPS] ['-tty='DEV] ['-s' SYMFILE] ['-e' PROG] ['-se' PROG]
|
||
['-c' CORE] ['-p' PROCID] ['-x' CMDS] ['-d' DIR] [PROG|PROG PROCID|PROG
|
||
CORE]
|
||
|
||
The purpose of a debugger such as GDB is to allow you to see what is
|
||
going on "inside" another program while it executes - or what another
|
||
program was doing at the moment it crashed.
|
||
|
||
GDB can do four main kinds of things (plus other things in support of
|
||
these) to help you catch bugs in the act:
|
||
|
||
* Start your program, specifying anything that might affect its
|
||
behavior.
|
||
|
||
* Make your program stop on specified conditions.
|
||
|
||
* Examine what has happened, when your program has stopped.
|
||
|
||
* Change things in your program, so you can experiment with
|
||
correcting the effects of one bug and go on to learn about another.
|
||
|
||
You can use GDB to debug programs written in C, C++, Fortran and
|
||
Modula-2.
|
||
|
||
GDB is invoked with the shell command 'gdb'. Once started, it reads
|
||
commands from the terminal until you tell it to exit with the GDB
|
||
command 'quit'. You can get online help from GDB itself by using the
|
||
command 'help'.
|
||
|
||
You can run 'gdb' with no arguments or options; but the most usual
|
||
way to start GDB is with one argument or two, specifying an executable
|
||
program as the argument:
|
||
|
||
gdb program
|
||
|
||
You can also start with both an executable program and a core file
|
||
specified:
|
||
|
||
gdb program core
|
||
|
||
You can, instead, specify a process ID as a second argument or use
|
||
option '-p', if you want to debug a running process:
|
||
|
||
gdb program 1234
|
||
gdb -p 1234
|
||
|
||
would attach GDB to process '1234'. With option '-p' you can omit the
|
||
PROGRAM filename.
|
||
|
||
Here are some of the most frequently needed GDB commands:
|
||
|
||
'break [FILE:]FUNCTION'
|
||
Set a breakpoint at FUNCTION (in FILE).
|
||
|
||
'run [ARGLIST]'
|
||
Start your program (with ARGLIST, if specified).
|
||
|
||
'bt'
|
||
Backtrace: display the program stack.
|
||
|
||
'print EXPR'
|
||
Display the value of an expression.
|
||
|
||
'c'
|
||
Continue running your program (after stopping, e.g. at a
|
||
breakpoint).
|
||
|
||
'next'
|
||
Execute next program line (after stopping); step _over_ any
|
||
function calls in the line.
|
||
|
||
'edit [FILE:]FUNCTION'
|
||
look at the program line where it is presently stopped.
|
||
|
||
'list [FILE:]FUNCTION'
|
||
type the text of the program in the vicinity of where it is
|
||
presently stopped.
|
||
|
||
'step'
|
||
Execute next program line (after stopping); step _into_ any
|
||
function calls in the line.
|
||
|
||
'help [NAME]'
|
||
Show information about GDB command NAME, or general information
|
||
about using GDB.
|
||
|
||
'quit'
|
||
Exit from GDB.
|
||
|
||
Any arguments other than options specify an executable file and core
|
||
file (or process ID); that is, the first argument encountered with no
|
||
associated option flag is equivalent to a '-se' option, and the second,
|
||
if any, is equivalent to a '-c' option if it's the name of a file. Many
|
||
options have both long and short forms; both are shown here. The long
|
||
forms are also recognized if you truncate them, so long as enough of the
|
||
option is present to be unambiguous. (If you prefer, you can flag
|
||
option arguments with '+' rather than '-', though we illustrate the more
|
||
usual convention.)
|
||
|
||
All the options and command line arguments you give are processed in
|
||
sequential order. The order makes a difference when the '-x' option is
|
||
used.
|
||
|
||
'-help'
|
||
'-h'
|
||
List all options, with brief explanations.
|
||
|
||
'-symbols=FILE'
|
||
'-s FILE'
|
||
Read symbol table from file FILE.
|
||
|
||
'-write'
|
||
Enable writing into executable and core files.
|
||
|
||
'-exec=FILE'
|
||
'-e FILE'
|
||
Use file FILE as the executable file to execute when appropriate,
|
||
and for examining pure data in conjunction with a core dump.
|
||
|
||
'-se=FILE'
|
||
Read symbol table from file FILE and use it as the executable file.
|
||
|
||
'-core=FILE'
|
||
'-c FILE'
|
||
Use file FILE as a core dump to examine.
|
||
|
||
'-command=FILE'
|
||
'-x FILE'
|
||
Execute GDB commands from file FILE.
|
||
|
||
'-ex COMMAND'
|
||
Execute given GDB COMMAND.
|
||
|
||
'-directory=DIRECTORY'
|
||
'-d DIRECTORY'
|
||
Add DIRECTORY to the path to search for source files.
|
||
|
||
'-nh'
|
||
Do not execute commands from '~/.gdbinit'.
|
||
|
||
'-nx'
|
||
'-n'
|
||
Do not execute commands from any '.gdbinit' initialization files.
|
||
|
||
'-quiet'
|
||
'-q'
|
||
"Quiet". Do not print the introductory and copyright messages.
|
||
These messages are also suppressed in batch mode.
|
||
|
||
'-batch'
|
||
Run in batch mode. Exit with status '0' after processing all the
|
||
command files specified with '-x' (and '.gdbinit', if not
|
||
inhibited). Exit with nonzero status if an error occurs in
|
||
executing the GDB commands in the command files.
|
||
|
||
Batch mode may be useful for running GDB as a filter, for example
|
||
to download and run a program on another computer; in order to make
|
||
this more useful, the message
|
||
|
||
Program exited normally.
|
||
|
||
(which is ordinarily issued whenever a program running under GDB
|
||
control terminates) is not issued when running in batch mode.
|
||
|
||
'-cd=DIRECTORY'
|
||
Run GDB using DIRECTORY as its working directory, instead of the
|
||
current directory.
|
||
|
||
'-fullname'
|
||
'-f'
|
||
Emacs sets this option when it runs GDB as a subprocess. It tells
|
||
GDB to output the full file name and line number in a standard,
|
||
recognizable fashion each time a stack frame is displayed (which
|
||
includes each time the program stops). This recognizable format
|
||
looks like two '\032' characters, followed by the file name, line
|
||
number and character position separated by colons, and a newline.
|
||
The Emacs-to-GDB interface program uses the two '\032' characters
|
||
as a signal to display the source code for the frame.
|
||
|
||
'-b BPS'
|
||
Set the line speed (baud rate or bits per second) of any serial
|
||
interface used by GDB for remote debugging.
|
||
|
||
'-tty=DEVICE'
|
||
Run using DEVICE for your program's standard input and output.
|
||
|
||
|
||
File: gdb.info, Node: gdbserver man, Next: gcore man, Prev: gdb man, Up: Man Pages
|
||
|
||
gdbserver man
|
||
=============
|
||
|
||
gdbserver COMM PROG [ARGS...]
|
||
|
||
gdbserver -attach COMM PID
|
||
|
||
gdbserver -multi COMM
|
||
|
||
'gdbserver' is a program that allows you to run GDB on a different
|
||
machine than the one which is running the program being debugged.
|
||
|
||
Usage (server (target) side)
|
||
----------------------------
|
||
|
||
First, you need to have a copy of the program you want to debug put onto
|
||
the target system. The program can be stripped to save space if needed,
|
||
as 'gdbserver' doesn't care about symbols. All symbol handling is taken
|
||
care of by the GDB running on the host system.
|
||
|
||
To use the server, you log on to the target system, and run the
|
||
'gdbserver' program. You must tell it (a) how to communicate with GDB,
|
||
(b) the name of your program, and (c) its arguments. The general syntax
|
||
is:
|
||
|
||
target> gdbserver COMM PROGRAM [ARGS ...]
|
||
|
||
For example, using a serial port, you might say:
|
||
|
||
target> gdbserver /dev/com1 emacs foo.txt
|
||
|
||
This tells 'gdbserver' to debug emacs with an argument of foo.txt,
|
||
and to communicate with GDB via '/dev/com1'. 'gdbserver' now waits
|
||
patiently for the host GDB to communicate with it.
|
||
|
||
To use a TCP connection, you could say:
|
||
|
||
target> gdbserver host:2345 emacs foo.txt
|
||
|
||
This says pretty much the same thing as the last example, except that
|
||
we are going to communicate with the 'host' GDB via TCP. The 'host:2345'
|
||
argument means that we are expecting to see a TCP connection from 'host'
|
||
to local TCP port 2345. (Currently, the 'host' part is ignored.) You
|
||
can choose any number you want for the port number as long as it does
|
||
not conflict with any existing TCP ports on the target system. This
|
||
same port number must be used in the host GDBs 'target remote' command,
|
||
which will be described shortly. Note that if you chose a port number
|
||
that conflicts with another service, 'gdbserver' will print an error
|
||
message and exit.
|
||
|
||
'gdbserver' can also attach to running programs. This is
|
||
accomplished via the '--attach' argument. The syntax is:
|
||
|
||
target> gdbserver --attach COMM PID
|
||
|
||
PID is the process ID of a currently running process. It isn't
|
||
necessary to point 'gdbserver' at a binary for the running process.
|
||
|
||
To start 'gdbserver' without supplying an initial command to run or
|
||
process ID to attach, use the '--multi' command line option. In such
|
||
case you should connect using 'target extended-remote' to start the
|
||
program you want to debug.
|
||
|
||
target> gdbserver --multi COMM
|
||
|
||
Usage (host side)
|
||
-----------------
|
||
|
||
You need an unstripped copy of the target program on your host system,
|
||
since GDB needs to examine its symbol tables and such. Start up GDB as
|
||
you normally would, with the target program as the first argument. (You
|
||
may need to use the '--baud' option if the serial line is running at
|
||
anything except 9600 baud.) That is 'gdb TARGET-PROG', or 'gdb --baud
|
||
BAUD TARGET-PROG'. After that, the only new command you need to know
|
||
about is 'target remote' (or 'target extended-remote'). Its argument is
|
||
either a device name (usually a serial device, like '/dev/ttyb'), or a
|
||
'HOST:PORT' descriptor. For example:
|
||
|
||
(gdb) target remote /dev/ttyb
|
||
|
||
communicates with the server via serial line '/dev/ttyb', and:
|
||
|
||
(gdb) target remote the-target:2345
|
||
|
||
communicates via a TCP connection to port 2345 on host 'the-target',
|
||
where you previously started up 'gdbserver' with the same port number.
|
||
Note that for TCP connections, you must start up 'gdbserver' prior to
|
||
using the 'target remote' command, otherwise you may get an error that
|
||
looks something like 'Connection refused'.
|
||
|
||
'gdbserver' can also debug multiple inferiors at once, described in
|
||
*note Inferiors and Programs::. In such case use the 'extended-remote'
|
||
GDB command variant:
|
||
|
||
(gdb) target extended-remote the-target:2345
|
||
|
||
The 'gdbserver' option '--multi' may or may not be used in such case.
|
||
|
||
There are three different modes for invoking 'gdbserver':
|
||
|
||
* Debug a specific program specified by its program name:
|
||
|
||
gdbserver COMM PROG [ARGS...]
|
||
|
||
The COMM parameter specifies how should the server communicate with
|
||
GDB; it is either a device name (to use a serial line), a TCP port
|
||
number (':1234'), or '-' or 'stdio' to use stdin/stdout of
|
||
'gdbserver'. Specify the name of the program to debug in PROG.
|
||
Any remaining arguments will be passed to the program verbatim.
|
||
When the program exits, GDB will close the connection, and
|
||
'gdbserver' will exit.
|
||
|
||
* Debug a specific program by specifying the process ID of a running
|
||
program:
|
||
|
||
gdbserver --attach COMM PID
|
||
|
||
The COMM parameter is as described above. Supply the process ID of
|
||
a running program in PID; GDB will do everything else. Like with
|
||
the previous mode, when the process PID exits, GDB will close the
|
||
connection, and 'gdbserver' will exit.
|
||
|
||
* Multi-process mode - debug more than one program/process:
|
||
|
||
gdbserver --multi COMM
|
||
|
||
In this mode, GDB can instruct 'gdbserver' which command(s) to run.
|
||
Unlike the other 2 modes, GDB will not close the connection when a
|
||
process being debugged exits, so you can debug several processes in
|
||
the same session.
|
||
|
||
In each of the modes you may specify these options:
|
||
|
||
'--help'
|
||
List all options, with brief explanations.
|
||
|
||
'--version'
|
||
This option causes 'gdbserver' to print its version number and
|
||
exit.
|
||
|
||
'--attach'
|
||
'gdbserver' will attach to a running program. The syntax is:
|
||
|
||
target> gdbserver --attach COMM PID
|
||
|
||
PID is the process ID of a currently running process. It isn't
|
||
necessary to point 'gdbserver' at a binary for the running process.
|
||
|
||
'--multi'
|
||
To start 'gdbserver' without supplying an initial command to run or
|
||
process ID to attach, use this command line option. Then you can
|
||
connect using 'target extended-remote' and start the program you
|
||
want to debug. The syntax is:
|
||
|
||
target> gdbserver --multi COMM
|
||
|
||
'--debug'
|
||
Instruct 'gdbserver' to display extra status information about the
|
||
debugging process. This option is intended for 'gdbserver'
|
||
development and for bug reports to the developers.
|
||
|
||
'--remote-debug'
|
||
Instruct 'gdbserver' to display remote protocol debug output. This
|
||
option is intended for 'gdbserver' development and for bug reports
|
||
to the developers.
|
||
|
||
'--debug-file=FILENAME'
|
||
Instruct 'gdbserver' to send any debug output to the given
|
||
FILENAME. This option is intended for 'gdbserver' development and
|
||
for bug reports to the developers.
|
||
|
||
'--debug-format=option1[,option2,...]'
|
||
Instruct 'gdbserver' to include extra information in each line of
|
||
debugging output. *Note Other Command-Line Arguments for
|
||
gdbserver::.
|
||
|
||
'--wrapper'
|
||
Specify a wrapper to launch programs for debugging. The option
|
||
should be followed by the name of the wrapper, then any
|
||
command-line arguments to pass to the wrapper, then '--' indicating
|
||
the end of the wrapper arguments.
|
||
|
||
'--once'
|
||
By default, 'gdbserver' keeps the listening TCP port open, so that
|
||
additional connections are possible. However, if you start
|
||
'gdbserver' with the '--once' option, it will stop listening for
|
||
any further connection attempts after connecting to the first GDB
|
||
session.
|
||
|
||
|
||
File: gdb.info, Node: gcore man, Next: gdbinit man, Prev: gdbserver man, Up: Man Pages
|
||
|
||
gcore
|
||
=====
|
||
|
||
gcore [-a] [-o PREFIX] PID1 [PID2...PIDN]
|
||
|
||
Generate core dumps of one or more running programs with process IDs
|
||
PID1, PID2, etc. A core file produced by 'gcore' is equivalent to one
|
||
produced by the kernel when the process crashes (and when 'ulimit -c'
|
||
was used to set up an appropriate core dump limit). However, unlike
|
||
after a crash, after 'gcore' finishes its job the program remains
|
||
running without any change.
|
||
|
||
'-a'
|
||
Dump all memory mappings. The actual effect of this option depends
|
||
on the Operating System. On GNU/Linux, it will disable
|
||
'use-coredump-filter' (*note set use-coredump-filter::) and enable
|
||
'dump-excluded-mappings' (*note set dump-excluded-mappings::).
|
||
|
||
'-o PREFIX'
|
||
The optional argument PREFIX specifies the prefix to be used when
|
||
composing the file names of the core dumps. The file name is
|
||
composed as 'PREFIX.PID', where PID is the process ID of the
|
||
running program being analyzed by 'gcore'. If not specified,
|
||
PREFIX defaults to GCORE.
|
||
|
||
|
||
File: gdb.info, Node: gdbinit man, Next: gdb-add-index man, Prev: gcore man, Up: Man Pages
|
||
|
||
gdbinit
|
||
=======
|
||
|
||
|
||
|
||
~/.gdbinit
|
||
|
||
./.gdbinit
|
||
|
||
These files contain GDB commands to automatically execute during GDB
|
||
startup. The lines of contents are canned sequences of commands,
|
||
described in *note Sequences::.
|
||
|
||
Please read more in *note Startup::.
|
||
|
||
'(not enabled with --with-system-gdbinit during compilation)'
|
||
System-wide initialization file. It is executed unless user
|
||
specified GDB option '-nx' or '-n'. See more in
|
||
'(not enabled with --with-system-gdbinit-dir during compilation)'
|
||
System-wide initialization directory. All files in this directory
|
||
are executed on startup unless user specified GDB option '-nx' or
|
||
'-n', as long as they have a recognized file extension. See more
|
||
in *note System-wide configuration::.
|
||
|
||
'~/.gdbinit'
|
||
User initialization file. It is executed unless user specified GDB
|
||
options '-nx', '-n' or '-nh'.
|
||
|
||
'./.gdbinit'
|
||
Initialization file for current directory. It may need to be
|
||
enabled with GDB security command 'set auto-load local-gdbinit'.
|
||
See more in *note Init File in the Current Directory::.
|
||
|
||
|
||
File: gdb.info, Node: gdb-add-index man, Prev: gdbinit man, Up: Man Pages
|
||
|
||
gdb-add-index
|
||
=============
|
||
|
||
gdb-add-index FILENAME
|
||
|
||
When GDB finds a symbol file, it scans the symbols in the file in
|
||
order to construct an internal symbol table. This lets most GDB
|
||
operations work quickly-at the cost of a delay early on. For large
|
||
programs, this delay can be quite lengthy, so GDB provides a way to
|
||
build an index, which speeds up startup.
|
||
|
||
To determine whether a file contains such an index, use the command
|
||
'readelf -S filename': the index is stored in a section named
|
||
'.gdb_index'. The index file can only be produced on systems which use
|
||
ELF binaries and DWARF debug information (i.e., sections named
|
||
'.debug_*').
|
||
|
||
'gdb-add-index' uses GDB and 'objdump' found in the 'PATH'
|
||
environment variable. If you want to use different versions of these
|
||
programs, you can specify them through the 'GDB' and 'OBJDUMP'
|
||
environment variables.
|
||
|
||
See more in *note Index Files::.
|
||
|
||
|
||
File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Man Pages, Up: Top
|
||
|
||
Appendix L GNU GENERAL PUBLIC LICENSE
|
||
*************************************
|
||
|
||
Version 3, 29 June 2007
|
||
|
||
Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
|
||
|
||
Everyone is permitted to copy and distribute verbatim copies of this
|
||
license document, but changing it is not allowed.
|
||
|
||
Preamble
|
||
========
|
||
|
||
The GNU General Public License is a free, copyleft license for software
|
||
and other kinds of works.
|
||
|
||
The licenses for most software and other practical works are designed
|
||
to take away your freedom to share and change the works. By contrast,
|
||
the GNU General Public License is intended to guarantee your freedom to
|
||
share and change all versions of a program--to make sure it remains free
|
||
software for all its users. We, the Free Software Foundation, use the
|
||
GNU General Public License for most of our software; it applies also to
|
||
any other work released this way by its authors. You can apply it to
|
||
your programs, too.
|
||
|
||
When we speak of free software, we are referring to freedom, not
|
||
price. Our General Public Licenses are designed to make sure that you
|
||
have the freedom to distribute copies of free software (and charge for
|
||
them if you wish), that you receive source code or can get it if you
|
||
want it, that you can change the software or use pieces of it in new
|
||
free programs, and that you know you can do these things.
|
||
|
||
To protect your rights, we need to prevent others from denying you
|
||
these rights or asking you to surrender the rights. Therefore, you have
|
||
certain responsibilities if you distribute copies of the software, or if
|
||
you modify it: responsibilities to respect the freedom of others.
|
||
|
||
For example, if you distribute copies of such a program, whether
|
||
gratis or for a fee, you must pass on to the recipients the same
|
||
freedoms that you received. You must make sure that they, too, receive
|
||
or can get the source code. And you must show them these terms so they
|
||
know their rights.
|
||
|
||
Developers that use the GNU GPL protect your rights with two steps:
|
||
(1) assert copyright on the software, and (2) offer you this License
|
||
giving you legal permission to copy, distribute and/or modify it.
|
||
|
||
For the developers' and authors' protection, the GPL clearly explains
|
||
that there is no warranty for this free software. For both users' and
|
||
authors' sake, the GPL requires that modified versions be marked as
|
||
changed, so that their problems will not be attributed erroneously to
|
||
authors of previous versions.
|
||
|
||
Some devices are designed to deny users access to install or run
|
||
modified versions of the software inside them, although the manufacturer
|
||
can do so. This is fundamentally incompatible with the aim of
|
||
protecting users' freedom to change the software. The systematic
|
||
pattern of such abuse occurs in the area of products for individuals to
|
||
use, which is precisely where it is most unacceptable. Therefore, we
|
||
have designed this version of the GPL to prohibit the practice for those
|
||
products. If such problems arise substantially in other domains, we
|
||
stand ready to extend this provision to those domains in future versions
|
||
of the GPL, as needed to protect the freedom of users.
|
||
|
||
Finally, every program is threatened constantly by software patents.
|
||
States should not allow patents to restrict development and use of
|
||
software on general-purpose computers, but in those that do, we wish to
|
||
avoid the special danger that patents applied to a free program could
|
||
make it effectively proprietary. To prevent this, the GPL assures that
|
||
patents cannot be used to render the program non-free.
|
||
|
||
The precise terms and conditions for copying, distribution and
|
||
modification follow.
|
||
|
||
TERMS AND CONDITIONS
|
||
====================
|
||
|
||
0. Definitions.
|
||
|
||
"This License" refers to version 3 of the GNU General Public
|
||
License.
|
||
|
||
"Copyright" also means copyright-like laws that apply to other
|
||
kinds of works, such as semiconductor masks.
|
||
|
||
"The Program" refers to any copyrightable work licensed under this
|
||
License. Each licensee is addressed as "you". "Licensees" and
|
||
"recipients" may be individuals or organizations.
|
||
|
||
To "modify" a work means to copy from or adapt all or part of the
|
||
work in a fashion requiring copyright permission, other than the
|
||
making of an exact copy. The resulting work is called a "modified
|
||
version" of the earlier work or a work "based on" the earlier work.
|
||
|
||
A "covered work" means either the unmodified Program or a work
|
||
based on the Program.
|
||
|
||
To "propagate" a work means to do anything with it that, without
|
||
permission, would make you directly or secondarily liable for
|
||
infringement under applicable copyright law, except executing it on
|
||
a computer or modifying a private copy. Propagation includes
|
||
copying, distribution (with or without modification), making
|
||
available to the public, and in some countries other activities as
|
||
well.
|
||
|
||
To "convey" a work means any kind of propagation that enables other
|
||
parties to make or receive copies. Mere interaction with a user
|
||
through a computer network, with no transfer of a copy, is not
|
||
conveying.
|
||
|
||
An interactive user interface displays "Appropriate Legal Notices"
|
||
to the extent that it includes a convenient and prominently visible
|
||
feature that (1) displays an appropriate copyright notice, and (2)
|
||
tells the user that there is no warranty for the work (except to
|
||
the extent that warranties are provided), that licensees may convey
|
||
the work under this License, and how to view a copy of this
|
||
License. If the interface presents a list of user commands or
|
||
options, such as a menu, a prominent item in the list meets this
|
||
criterion.
|
||
|
||
1. Source Code.
|
||
|
||
The "source code" for a work means the preferred form of the work
|
||
for making modifications to it. "Object code" means any non-source
|
||
form of a work.
|
||
|
||
A "Standard Interface" means an interface that either is an
|
||
official standard defined by a recognized standards body, or, in
|
||
the case of interfaces specified for a particular programming
|
||
language, one that is widely used among developers working in that
|
||
language.
|
||
|
||
The "System Libraries" of an executable work include anything,
|
||
other than the work as a whole, that (a) is included in the normal
|
||
form of packaging a Major Component, but which is not part of that
|
||
Major Component, and (b) serves only to enable use of the work with
|
||
that Major Component, or to implement a Standard Interface for
|
||
which an implementation is available to the public in source code
|
||
form. A "Major Component", in this context, means a major
|
||
essential component (kernel, window system, and so on) of the
|
||
specific operating system (if any) on which the executable work
|
||
runs, or a compiler used to produce the work, or an object code
|
||
interpreter used to run it.
|
||
|
||
The "Corresponding Source" for a work in object code form means all
|
||
the source code needed to generate, install, and (for an executable
|
||
work) run the object code and to modify the work, including scripts
|
||
to control those activities. However, it does not include the
|
||
work's System Libraries, or general-purpose tools or generally
|
||
available free programs which are used unmodified in performing
|
||
those activities but which are not part of the work. For example,
|
||
Corresponding Source includes interface definition files associated
|
||
with source files for the work, and the source code for shared
|
||
libraries and dynamically linked subprograms that the work is
|
||
specifically designed to require, such as by intimate data
|
||
communication or control flow between those subprograms and other
|
||
parts of the work.
|
||
|
||
The Corresponding Source need not include anything that users can
|
||
regenerate automatically from other parts of the Corresponding
|
||
Source.
|
||
|
||
The Corresponding Source for a work in source code form is that
|
||
same work.
|
||
|
||
2. Basic Permissions.
|
||
|
||
All rights granted under this License are granted for the term of
|
||
copyright on the Program, and are irrevocable provided the stated
|
||
conditions are met. This License explicitly affirms your unlimited
|
||
permission to run the unmodified Program. The output from running
|
||
a covered work is covered by this License only if the output, given
|
||
its content, constitutes a covered work. This License acknowledges
|
||
your rights of fair use or other equivalent, as provided by
|
||
copyright law.
|
||
|
||
You may make, run and propagate covered works that you do not
|
||
convey, without conditions so long as your license otherwise
|
||
remains in force. You may convey covered works to others for the
|
||
sole purpose of having them make modifications exclusively for you,
|
||
or provide you with facilities for running those works, provided
|
||
that you comply with the terms of this License in conveying all
|
||
material for which you do not control copyright. Those thus making
|
||
or running the covered works for you must do so exclusively on your
|
||
behalf, under your direction and control, on terms that prohibit
|
||
them from making any copies of your copyrighted material outside
|
||
their relationship with you.
|
||
|
||
Conveying under any other circumstances is permitted solely under
|
||
the conditions stated below. Sublicensing is not allowed; section
|
||
10 makes it unnecessary.
|
||
|
||
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
|
||
|
||
No covered work shall be deemed part of an effective technological
|
||
measure under any applicable law fulfilling obligations under
|
||
article 11 of the WIPO copyright treaty adopted on 20 December
|
||
1996, or similar laws prohibiting or restricting circumvention of
|
||
such measures.
|
||
|
||
When you convey a covered work, you waive any legal power to forbid
|
||
circumvention of technological measures to the extent such
|
||
circumvention is effected by exercising rights under this License
|
||
with respect to the covered work, and you disclaim any intention to
|
||
limit operation or modification of the work as a means of
|
||
enforcing, against the work's users, your or third parties' legal
|
||
rights to forbid circumvention of technological measures.
|
||
|
||
4. Conveying Verbatim Copies.
|
||
|
||
You may convey verbatim copies of the Program's source code as you
|
||
receive it, in any medium, provided that you conspicuously and
|
||
appropriately publish on each copy an appropriate copyright notice;
|
||
keep intact all notices stating that this License and any
|
||
non-permissive terms added in accord with section 7 apply to the
|
||
code; keep intact all notices of the absence of any warranty; and
|
||
give all recipients a copy of this License along with the Program.
|
||
|
||
You may charge any price or no price for each copy that you convey,
|
||
and you may offer support or warranty protection for a fee.
|
||
|
||
5. Conveying Modified Source Versions.
|
||
|
||
You may convey a work based on the Program, or the modifications to
|
||
produce it from the Program, in the form of source code under the
|
||
terms of section 4, provided that you also meet all of these
|
||
conditions:
|
||
|
||
a. The work must carry prominent notices stating that you
|
||
modified it, and giving a relevant date.
|
||
|
||
b. The work must carry prominent notices stating that it is
|
||
released under this License and any conditions added under
|
||
section 7. This requirement modifies the requirement in
|
||
section 4 to "keep intact all notices".
|
||
|
||
c. You must license the entire work, as a whole, under this
|
||
License to anyone who comes into possession of a copy. This
|
||
License will therefore apply, along with any applicable
|
||
section 7 additional terms, to the whole of the work, and all
|
||
its parts, regardless of how they are packaged. This License
|
||
gives no permission to license the work in any other way, but
|
||
it does not invalidate such permission if you have separately
|
||
received it.
|
||
|
||
d. If the work has interactive user interfaces, each must display
|
||
Appropriate Legal Notices; however, if the Program has
|
||
interactive interfaces that do not display Appropriate Legal
|
||
Notices, your work need not make them do so.
|
||
|
||
A compilation of a covered work with other separate and independent
|
||
works, which are not by their nature extensions of the covered
|
||
work, and which are not combined with it such as to form a larger
|
||
program, in or on a volume of a storage or distribution medium, is
|
||
called an "aggregate" if the compilation and its resulting
|
||
copyright are not used to limit the access or legal rights of the
|
||
compilation's users beyond what the individual works permit.
|
||
Inclusion of a covered work in an aggregate does not cause this
|
||
License to apply to the other parts of the aggregate.
|
||
|
||
6. Conveying Non-Source Forms.
|
||
|
||
You may convey a covered work in object code form under the terms
|
||
of sections 4 and 5, provided that you also convey the
|
||
machine-readable Corresponding Source under the terms of this
|
||
License, in one of these ways:
|
||
|
||
a. Convey the object code in, or embodied in, a physical product
|
||
(including a physical distribution medium), accompanied by the
|
||
Corresponding Source fixed on a durable physical medium
|
||
customarily used for software interchange.
|
||
|
||
b. Convey the object code in, or embodied in, a physical product
|
||
(including a physical distribution medium), accompanied by a
|
||
written offer, valid for at least three years and valid for as
|
||
long as you offer spare parts or customer support for that
|
||
product model, to give anyone who possesses the object code
|
||
either (1) a copy of the Corresponding Source for all the
|
||
software in the product that is covered by this License, on a
|
||
durable physical medium customarily used for software
|
||
interchange, for a price no more than your reasonable cost of
|
||
physically performing this conveying of source, or (2) access
|
||
to copy the Corresponding Source from a network server at no
|
||
charge.
|
||
|
||
c. Convey individual copies of the object code with a copy of the
|
||
written offer to provide the Corresponding Source. This
|
||
alternative is allowed only occasionally and noncommercially,
|
||
and only if you received the object code with such an offer,
|
||
in accord with subsection 6b.
|
||
|
||
d. Convey the object code by offering access from a designated
|
||
place (gratis or for a charge), and offer equivalent access to
|
||
the Corresponding Source in the same way through the same
|
||
place at no further charge. You need not require recipients
|
||
to copy the Corresponding Source along with the object code.
|
||
If the place to copy the object code is a network server, the
|
||
Corresponding Source may be on a different server (operated by
|
||
you or a third party) that supports equivalent copying
|
||
facilities, provided you maintain clear directions next to the
|
||
object code saying where to find the Corresponding Source.
|
||
Regardless of what server hosts the Corresponding Source, you
|
||
remain obligated to ensure that it is available for as long as
|
||
needed to satisfy these requirements.
|
||
|
||
e. Convey the object code using peer-to-peer transmission,
|
||
provided you inform other peers where the object code and
|
||
Corresponding Source of the work are being offered to the
|
||
general public at no charge under subsection 6d.
|
||
|
||
A separable portion of the object code, whose source code is
|
||
excluded from the Corresponding Source as a System Library, need
|
||
not be included in conveying the object code work.
|
||
|
||
A "User Product" is either (1) a "consumer product", which means
|
||
any tangible personal property which is normally used for personal,
|
||
family, or household purposes, or (2) anything designed or sold for
|
||
incorporation into a dwelling. In determining whether a product is
|
||
a consumer product, doubtful cases shall be resolved in favor of
|
||
coverage. For a particular product received by a particular user,
|
||
"normally used" refers to a typical or common use of that class of
|
||
product, regardless of the status of the particular user or of the
|
||
way in which the particular user actually uses, or expects or is
|
||
expected to use, the product. A product is a consumer product
|
||
regardless of whether the product has substantial commercial,
|
||
industrial or non-consumer uses, unless such uses represent the
|
||
only significant mode of use of the product.
|
||
|
||
"Installation Information" for a User Product means any methods,
|
||
procedures, authorization keys, or other information required to
|
||
install and execute modified versions of a covered work in that
|
||
User Product from a modified version of its Corresponding Source.
|
||
The information must suffice to ensure that the continued
|
||
functioning of the modified object code is in no case prevented or
|
||
interfered with solely because modification has been made.
|
||
|
||
If you convey an object code work under this section in, or with,
|
||
or specifically for use in, a User Product, and the conveying
|
||
occurs as part of a transaction in which the right of possession
|
||
and use of the User Product is transferred to the recipient in
|
||
perpetuity or for a fixed term (regardless of how the transaction
|
||
is characterized), the Corresponding Source conveyed under this
|
||
section must be accompanied by the Installation Information. But
|
||
this requirement does not apply if neither you nor any third party
|
||
retains the ability to install modified object code on the User
|
||
Product (for example, the work has been installed in ROM).
|
||
|
||
The requirement to provide Installation Information does not
|
||
include a requirement to continue to provide support service,
|
||
warranty, or updates for a work that has been modified or installed
|
||
by the recipient, or for the User Product in which it has been
|
||
modified or installed. Access to a network may be denied when the
|
||
modification itself materially and adversely affects the operation
|
||
of the network or violates the rules and protocols for
|
||
communication across the network.
|
||
|
||
Corresponding Source conveyed, and Installation Information
|
||
provided, in accord with this section must be in a format that is
|
||
publicly documented (and with an implementation available to the
|
||
public in source code form), and must require no special password
|
||
or key for unpacking, reading or copying.
|
||
|
||
7. Additional Terms.
|
||
|
||
"Additional permissions" are terms that supplement the terms of
|
||
this License by making exceptions from one or more of its
|
||
conditions. Additional permissions that are applicable to the
|
||
entire Program shall be treated as though they were included in
|
||
this License, to the extent that they are valid under applicable
|
||
law. If additional permissions apply only to part of the Program,
|
||
that part may be used separately under those permissions, but the
|
||
entire Program remains governed by this License without regard to
|
||
the additional permissions.
|
||
|
||
When you convey a copy of a covered work, you may at your option
|
||
remove any additional permissions from that copy, or from any part
|
||
of it. (Additional permissions may be written to require their own
|
||
removal in certain cases when you modify the work.) You may place
|
||
additional permissions on material, added by you to a covered work,
|
||
for which you have or can give appropriate copyright permission.
|
||
|
||
Notwithstanding any other provision of this License, for material
|
||
you add to a covered work, you may (if authorized by the copyright
|
||
holders of that material) supplement the terms of this License with
|
||
terms:
|
||
|
||
a. Disclaiming warranty or limiting liability differently from
|
||
the terms of sections 15 and 16 of this License; or
|
||
|
||
b. Requiring preservation of specified reasonable legal notices
|
||
or author attributions in that material or in the Appropriate
|
||
Legal Notices displayed by works containing it; or
|
||
|
||
c. Prohibiting misrepresentation of the origin of that material,
|
||
or requiring that modified versions of such material be marked
|
||
in reasonable ways as different from the original version; or
|
||
|
||
d. Limiting the use for publicity purposes of names of licensors
|
||
or authors of the material; or
|
||
|
||
e. Declining to grant rights under trademark law for use of some
|
||
trade names, trademarks, or service marks; or
|
||
|
||
f. Requiring indemnification of licensors and authors of that
|
||
material by anyone who conveys the material (or modified
|
||
versions of it) with contractual assumptions of liability to
|
||
the recipient, for any liability that these contractual
|
||
assumptions directly impose on those licensors and authors.
|
||
|
||
All other non-permissive additional terms are considered "further
|
||
restrictions" within the meaning of section 10. If the Program as
|
||
you received it, or any part of it, contains a notice stating that
|
||
it is governed by this License along with a term that is a further
|
||
restriction, you may remove that term. If a license document
|
||
contains a further restriction but permits relicensing or conveying
|
||
under this License, you may add to a covered work material governed
|
||
by the terms of that license document, provided that the further
|
||
restriction does not survive such relicensing or conveying.
|
||
|
||
If you add terms to a covered work in accord with this section, you
|
||
must place, in the relevant source files, a statement of the
|
||
additional terms that apply to those files, or a notice indicating
|
||
where to find the applicable terms.
|
||
|
||
Additional terms, permissive or non-permissive, may be stated in
|
||
the form of a separately written license, or stated as exceptions;
|
||
the above requirements apply either way.
|
||
|
||
8. Termination.
|
||
|
||
You may not propagate or modify a covered work except as expressly
|
||
provided under this License. Any attempt otherwise to propagate or
|
||
modify it is void, and will automatically terminate your rights
|
||
under this License (including any patent licenses granted under the
|
||
third paragraph of section 11).
|
||
|
||
However, if you cease all violation of this License, then your
|
||
license from a particular copyright holder is reinstated (a)
|
||
provisionally, unless and until the copyright holder explicitly and
|
||
finally terminates your license, and (b) permanently, if the
|
||
copyright holder fails to notify you of the violation by some
|
||
reasonable means prior to 60 days after the cessation.
|
||
|
||
Moreover, your license from a particular copyright holder is
|
||
reinstated permanently if the copyright holder notifies you of the
|
||
violation by some reasonable means, this is the first time you have
|
||
received notice of violation of this License (for any work) from
|
||
that copyright holder, and you cure the violation prior to 30 days
|
||
after your receipt of the notice.
|
||
|
||
Termination of your rights under this section does not terminate
|
||
the licenses of parties who have received copies or rights from you
|
||
under this License. If your rights have been terminated and not
|
||
permanently reinstated, you do not qualify to receive new licenses
|
||
for the same material under section 10.
|
||
|
||
9. Acceptance Not Required for Having Copies.
|
||
|
||
You are not required to accept this License in order to receive or
|
||
run a copy of the Program. Ancillary propagation of a covered work
|
||
occurring solely as a consequence of using peer-to-peer
|
||
transmission to receive a copy likewise does not require
|
||
acceptance. However, nothing other than this License grants you
|
||
permission to propagate or modify any covered work. These actions
|
||
infringe copyright if you do not accept this License. Therefore,
|
||
by modifying or propagating a covered work, you indicate your
|
||
acceptance of this License to do so.
|
||
|
||
10. Automatic Licensing of Downstream Recipients.
|
||
|
||
Each time you convey a covered work, the recipient automatically
|
||
receives a license from the original licensors, to run, modify and
|
||
propagate that work, subject to this License. You are not
|
||
responsible for enforcing compliance by third parties with this
|
||
License.
|
||
|
||
An "entity transaction" is a transaction transferring control of an
|
||
organization, or substantially all assets of one, or subdividing an
|
||
organization, or merging organizations. If propagation of a
|
||
covered work results from an entity transaction, each party to that
|
||
transaction who receives a copy of the work also receives whatever
|
||
licenses to the work the party's predecessor in interest had or
|
||
could give under the previous paragraph, plus a right to possession
|
||
of the Corresponding Source of the work from the predecessor in
|
||
interest, if the predecessor has it or can get it with reasonable
|
||
efforts.
|
||
|
||
You may not impose any further restrictions on the exercise of the
|
||
rights granted or affirmed under this License. For example, you
|
||
may not impose a license fee, royalty, or other charge for exercise
|
||
of rights granted under this License, and you may not initiate
|
||
litigation (including a cross-claim or counterclaim in a lawsuit)
|
||
alleging that any patent claim is infringed by making, using,
|
||
selling, offering for sale, or importing the Program or any portion
|
||
of it.
|
||
|
||
11. Patents.
|
||
|
||
A "contributor" is a copyright holder who authorizes use under this
|
||
License of the Program or a work on which the Program is based.
|
||
The work thus licensed is called the contributor's "contributor
|
||
version".
|
||
|
||
A contributor's "essential patent claims" are all patent claims
|
||
owned or controlled by the contributor, whether already acquired or
|
||
hereafter acquired, that would be infringed by some manner,
|
||
permitted by this License, of making, using, or selling its
|
||
contributor version, but do not include claims that would be
|
||
infringed only as a consequence of further modification of the
|
||
contributor version. For purposes of this definition, "control"
|
||
includes the right to grant patent sublicenses in a manner
|
||
consistent with the requirements of this License.
|
||
|
||
Each contributor grants you a non-exclusive, worldwide,
|
||
royalty-free patent license under the contributor's essential
|
||
patent claims, to make, use, sell, offer for sale, import and
|
||
otherwise run, modify and propagate the contents of its contributor
|
||
version.
|
||
|
||
In the following three paragraphs, a "patent license" is any
|
||
express agreement or commitment, however denominated, not to
|
||
enforce a patent (such as an express permission to practice a
|
||
patent or covenant not to sue for patent infringement). To "grant"
|
||
such a patent license to a party means to make such an agreement or
|
||
commitment not to enforce a patent against the party.
|
||
|
||
If you convey a covered work, knowingly relying on a patent
|
||
license, and the Corresponding Source of the work is not available
|
||
for anyone to copy, free of charge and under the terms of this
|
||
License, through a publicly available network server or other
|
||
readily accessible means, then you must either (1) cause the
|
||
Corresponding Source to be so available, or (2) arrange to deprive
|
||
yourself of the benefit of the patent license for this particular
|
||
work, or (3) arrange, in a manner consistent with the requirements
|
||
of this License, to extend the patent license to downstream
|
||
recipients. "Knowingly relying" means you have actual knowledge
|
||
that, but for the patent license, your conveying the covered work
|
||
in a country, or your recipient's use of the covered work in a
|
||
country, would infringe one or more identifiable patents in that
|
||
country that you have reason to believe are valid.
|
||
|
||
If, pursuant to or in connection with a single transaction or
|
||
arrangement, you convey, or propagate by procuring conveyance of, a
|
||
covered work, and grant a patent license to some of the parties
|
||
receiving the covered work authorizing them to use, propagate,
|
||
modify or convey a specific copy of the covered work, then the
|
||
patent license you grant is automatically extended to all
|
||
recipients of the covered work and works based on it.
|
||
|
||
A patent license is "discriminatory" if it does not include within
|
||
the scope of its coverage, prohibits the exercise of, or is
|
||
conditioned on the non-exercise of one or more of the rights that
|
||
are specifically granted under this License. You may not convey a
|
||
covered work if you are a party to an arrangement with a third
|
||
party that is in the business of distributing software, under which
|
||
you make payment to the third party based on the extent of your
|
||
activity of conveying the work, and under which the third party
|
||
grants, to any of the parties who would receive the covered work
|
||
from you, a discriminatory patent license (a) in connection with
|
||
copies of the covered work conveyed by you (or copies made from
|
||
those copies), or (b) primarily for and in connection with specific
|
||
products or compilations that contain the covered work, unless you
|
||
entered into that arrangement, or that patent license was granted,
|
||
prior to 28 March 2007.
|
||
|
||
Nothing in this License shall be construed as excluding or limiting
|
||
any implied license or other defenses to infringement that may
|
||
otherwise be available to you under applicable patent law.
|
||
|
||
12. No Surrender of Others' Freedom.
|
||
|
||
If conditions are imposed on you (whether by court order, agreement
|
||
or otherwise) that contradict the conditions of this License, they
|
||
do not excuse you from the conditions of this License. If you
|
||
cannot convey a covered work so as to satisfy simultaneously your
|
||
obligations under this License and any other pertinent obligations,
|
||
then as a consequence you may not convey it at all. For example,
|
||
if you agree to terms that obligate you to collect a royalty for
|
||
further conveying from those to whom you convey the Program, the
|
||
only way you could satisfy both those terms and this License would
|
||
be to refrain entirely from conveying the Program.
|
||
|
||
13. Use with the GNU Affero General Public License.
|
||
|
||
Notwithstanding any other provision of this License, you have
|
||
permission to link or combine any covered work with a work licensed
|
||
under version 3 of the GNU Affero General Public License into a
|
||
single combined work, and to convey the resulting work. The terms
|
||
of this License will continue to apply to the part which is the
|
||
covered work, but the special requirements of the GNU Affero
|
||
General Public License, section 13, concerning interaction through
|
||
a network will apply to the combination as such.
|
||
|
||
14. Revised Versions of this License.
|
||
|
||
The Free Software Foundation may publish revised and/or new
|
||
versions of the GNU General Public License from time to time. Such
|
||
new versions will be similar in spirit to the present version, but
|
||
may differ in detail to address new problems or concerns.
|
||
|
||
Each version is given a distinguishing version number. If the
|
||
Program specifies that a certain numbered version of the GNU
|
||
General Public License "or any later version" applies to it, you
|
||
have the option of following the terms and conditions either of
|
||
that numbered version or of any later version published by the Free
|
||
Software Foundation. If the Program does not specify a version
|
||
number of the GNU General Public License, you may choose any
|
||
version ever published by the Free Software Foundation.
|
||
|
||
If the Program specifies that a proxy can decide which future
|
||
versions of the GNU General Public License can be used, that
|
||
proxy's public statement of acceptance of a version permanently
|
||
authorizes you to choose that version for the Program.
|
||
|
||
Later license versions may give you additional or different
|
||
permissions. However, no additional obligations are imposed on any
|
||
author or copyright holder as a result of your choosing to follow a
|
||
later version.
|
||
|
||
15. Disclaimer of Warranty.
|
||
|
||
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
|
||
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
|
||
COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS"
|
||
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
|
||
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
||
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
|
||
RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
|
||
SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
|
||
NECESSARY SERVICING, REPAIR OR CORRECTION.
|
||
|
||
16. Limitation of Liability.
|
||
|
||
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
|
||
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
|
||
AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
|
||
DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
|
||
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
|
||
THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
|
||
BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
|
||
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
|
||
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
|
||
THE POSSIBILITY OF SUCH DAMAGES.
|
||
|
||
17. Interpretation of Sections 15 and 16.
|
||
|
||
If the disclaimer of warranty and limitation of liability provided
|
||
above cannot be given local legal effect according to their terms,
|
||
reviewing courts shall apply local law that most closely
|
||
approximates an absolute waiver of all civil liability in
|
||
connection with the Program, unless a warranty or assumption of
|
||
liability accompanies a copy of the Program in return for a fee.
|
||
|
||
END OF TERMS AND CONDITIONS
|
||
===========================
|
||
|
||
How to Apply These Terms to Your New Programs
|
||
=============================================
|
||
|
||
If you develop a new program, and you want it to be of the greatest
|
||
possible use to the public, the best way to achieve this is to make it
|
||
free software which everyone can redistribute and change under these
|
||
terms.
|
||
|
||
To do so, attach the following notices to the program. It is safest
|
||
to attach them to the start of each source file to most effectively
|
||
state the exclusion of warranty; and each file should have at least the
|
||
"copyright" line and a pointer to where the full notice is found.
|
||
|
||
ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
|
||
Copyright (C) YEAR NAME OF AUTHOR
|
||
|
||
This program is free software: you can redistribute it and/or modify
|
||
it under the terms of the GNU General Public License as published by
|
||
the Free Software Foundation, either version 3 of the License, or (at
|
||
your option) any later version.
|
||
|
||
This program is distributed in the hope that it will be useful, but
|
||
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
General Public License for more details.
|
||
|
||
You should have received a copy of the GNU General Public License
|
||
along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||
|
||
Also add information on how to contact you by electronic and paper
|
||
mail.
|
||
|
||
If the program does terminal interaction, make it output a short
|
||
notice like this when it starts in an interactive mode:
|
||
|
||
PROGRAM Copyright (C) YEAR NAME OF AUTHOR
|
||
This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
|
||
This is free software, and you are welcome to redistribute it
|
||
under certain conditions; type 'show c' for details.
|
||
|
||
The hypothetical commands 'show w' and 'show c' should show the
|
||
appropriate parts of the General Public License. Of course, your
|
||
program's commands might be different; for a GUI interface, you would
|
||
use an "about box".
|
||
|
||
You should also get your employer (if you work as a programmer) or
|
||
school, if any, to sign a "copyright disclaimer" for the program, if
|
||
necessary. For more information on this, and how to apply and follow
|
||
the GNU GPL, see <http://www.gnu.org/licenses/>.
|
||
|
||
The GNU General Public License does not permit incorporating your
|
||
program into proprietary programs. If your program is a subroutine
|
||
library, you may consider it more useful to permit linking proprietary
|
||
applications with the library. If this is what you want to do, use the
|
||
GNU Lesser General Public License instead of this License. But first,
|
||
please read <http://www.gnu.org/philosophy/why-not-lgpl.html>.
|
||
|
||
|
||
File: gdb.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: Copying, Up: Top
|
||
|
||
Appendix M GNU Free Documentation License
|
||
*****************************************
|
||
|
||
Version 1.3, 3 November 2008
|
||
|
||
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
|
||
<http://fsf.org/>
|
||
|
||
Everyone is permitted to copy and distribute verbatim copies
|
||
of this license document, but changing it is not allowed.
|
||
|
||
0. PREAMBLE
|
||
|
||
The purpose of this License is to make a manual, textbook, or other
|
||
functional and useful document "free" in the sense of freedom: to
|
||
assure everyone the effective freedom to copy and redistribute it,
|
||
with or without modifying it, either commercially or
|
||
noncommercially. Secondarily, this License preserves for the
|
||
author and publisher a way to get credit for their work, while not
|
||
being considered responsible for modifications made by others.
|
||
|
||
This License is a kind of "copyleft", which means that derivative
|
||
works of the document must themselves be free in the same sense.
|
||
It complements the GNU General Public License, which is a copyleft
|
||
license designed for free software.
|
||
|
||
We have designed this License in order to use it for manuals for
|
||
free software, because free software needs free documentation: a
|
||
free program should come with manuals providing the same freedoms
|
||
that the software does. But this License is not limited to
|
||
software manuals; it can be used for any textual work, regardless
|
||
of subject matter or whether it is published as a printed book. We
|
||
recommend this License principally for works whose purpose is
|
||
instruction or reference.
|
||
|
||
1. APPLICABILITY AND DEFINITIONS
|
||
|
||
This License applies to any manual or other work, in any medium,
|
||
that contains a notice placed by the copyright holder saying it can
|
||
be distributed under the terms of this License. Such a notice
|
||
grants a world-wide, royalty-free license, unlimited in duration,
|
||
to use that work under the conditions stated herein. The
|
||
"Document", below, refers to any such manual or work. Any member
|
||
of the public is a licensee, and is addressed as "you". You accept
|
||
the license if you copy, modify or distribute the work in a way
|
||
requiring permission under copyright law.
|
||
|
||
A "Modified Version" of the Document means any work containing the
|
||
Document or a portion of it, either copied verbatim, or with
|
||
modifications and/or translated into another language.
|
||
|
||
A "Secondary Section" is a named appendix or a front-matter section
|
||
of the Document that deals exclusively with the relationship of the
|
||
publishers or authors of the Document to the Document's overall
|
||
subject (or to related matters) and contains nothing that could
|
||
fall directly within that overall subject. (Thus, if the Document
|
||
is in part a textbook of mathematics, a Secondary Section may not
|
||
explain any mathematics.) The relationship could be a matter of
|
||
historical connection with the subject or with related matters, or
|
||
of legal, commercial, philosophical, ethical or political position
|
||
regarding them.
|
||
|
||
The "Invariant Sections" are certain Secondary Sections whose
|
||
titles are designated, as being those of Invariant Sections, in the
|
||
notice that says that the Document is released under this License.
|
||
If a section does not fit the above definition of Secondary then it
|
||
is not allowed to be designated as Invariant. The Document may
|
||
contain zero Invariant Sections. If the Document does not identify
|
||
any Invariant Sections then there are none.
|
||
|
||
The "Cover Texts" are certain short passages of text that are
|
||
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
|
||
that says that the Document is released under this License. A
|
||
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
|
||
be at most 25 words.
|
||
|
||
A "Transparent" copy of the Document means a machine-readable copy,
|
||
represented in a format whose specification is available to the
|
||
general public, that is suitable for revising the document
|
||
straightforwardly with generic text editors or (for images composed
|
||
of pixels) generic paint programs or (for drawings) some widely
|
||
available drawing editor, and that is suitable for input to text
|
||
formatters or for automatic translation to a variety of formats
|
||
suitable for input to text formatters. A copy made in an otherwise
|
||
Transparent file format whose markup, or absence of markup, has
|
||
been arranged to thwart or discourage subsequent modification by
|
||
readers is not Transparent. An image format is not Transparent if
|
||
used for any substantial amount of text. A copy that is not
|
||
"Transparent" is called "Opaque".
|
||
|
||
Examples of suitable formats for Transparent copies include plain
|
||
ASCII without markup, Texinfo input format, LaTeX input format,
|
||
SGML or XML using a publicly available DTD, and standard-conforming
|
||
simple HTML, PostScript or PDF designed for human modification.
|
||
Examples of transparent image formats include PNG, XCF and JPG.
|
||
Opaque formats include proprietary formats that can be read and
|
||
edited only by proprietary word processors, SGML or XML for which
|
||
the DTD and/or processing tools are not generally available, and
|
||
the machine-generated HTML, PostScript or PDF produced by some word
|
||
processors for output purposes only.
|
||
|
||
The "Title Page" means, for a printed book, the title page itself,
|
||
plus such following pages as are needed to hold, legibly, the
|
||
material this License requires to appear in the title page. For
|
||
works in formats which do not have any title page as such, "Title
|
||
Page" means the text near the most prominent appearance of the
|
||
work's title, preceding the beginning of the body of the text.
|
||
|
||
The "publisher" means any person or entity that distributes copies
|
||
of the Document to the public.
|
||
|
||
A section "Entitled XYZ" means a named subunit of the Document
|
||
whose title either is precisely XYZ or contains XYZ in parentheses
|
||
following text that translates XYZ in another language. (Here XYZ
|
||
stands for a specific section name mentioned below, such as
|
||
"Acknowledgements", "Dedications", "Endorsements", or "History".)
|
||
To "Preserve the Title" of such a section when you modify the
|
||
Document means that it remains a section "Entitled XYZ" according
|
||
to this definition.
|
||
|
||
The Document may include Warranty Disclaimers next to the notice
|
||
which states that this License applies to the Document. These
|
||
Warranty Disclaimers are considered to be included by reference in
|
||
this License, but only as regards disclaiming warranties: any other
|
||
implication that these Warranty Disclaimers may have is void and
|
||
has no effect on the meaning of this License.
|
||
|
||
2. VERBATIM COPYING
|
||
|
||
You may copy and distribute the Document in any medium, either
|
||
commercially or noncommercially, provided that this License, the
|
||
copyright notices, and the license notice saying this License
|
||
applies to the Document are reproduced in all copies, and that you
|
||
add no other conditions whatsoever to those of this License. You
|
||
may not use technical measures to obstruct or control the reading
|
||
or further copying of the copies you make or distribute. However,
|
||
you may accept compensation in exchange for copies. If you
|
||
distribute a large enough number of copies you must also follow the
|
||
conditions in section 3.
|
||
|
||
You may also lend copies, under the same conditions stated above,
|
||
and you may publicly display copies.
|
||
|
||
3. COPYING IN QUANTITY
|
||
|
||
If you publish printed copies (or copies in media that commonly
|
||
have printed covers) of the Document, numbering more than 100, and
|
||
the Document's license notice requires Cover Texts, you must
|
||
enclose the copies in covers that carry, clearly and legibly, all
|
||
these Cover Texts: Front-Cover Texts on the front cover, and
|
||
Back-Cover Texts on the back cover. Both covers must also clearly
|
||
and legibly identify you as the publisher of these copies. The
|
||
front cover must present the full title with all words of the title
|
||
equally prominent and visible. You may add other material on the
|
||
covers in addition. Copying with changes limited to the covers, as
|
||
long as they preserve the title of the Document and satisfy these
|
||
conditions, can be treated as verbatim copying in other respects.
|
||
|
||
If the required texts for either cover are too voluminous to fit
|
||
legibly, you should put the first ones listed (as many as fit
|
||
reasonably) on the actual cover, and continue the rest onto
|
||
adjacent pages.
|
||
|
||
If you publish or distribute Opaque copies of the Document
|
||
numbering more than 100, you must either include a machine-readable
|
||
Transparent copy along with each Opaque copy, or state in or with
|
||
each Opaque copy a computer-network location from which the general
|
||
network-using public has access to download using public-standard
|
||
network protocols a complete Transparent copy of the Document, free
|
||
of added material. If you use the latter option, you must take
|
||
reasonably prudent steps, when you begin distribution of Opaque
|
||
copies in quantity, to ensure that this Transparent copy will
|
||
remain thus accessible at the stated location until at least one
|
||
year after the last time you distribute an Opaque copy (directly or
|
||
through your agents or retailers) of that edition to the public.
|
||
|
||
It is requested, but not required, that you contact the authors of
|
||
the Document well before redistributing any large number of copies,
|
||
to give them a chance to provide you with an updated version of the
|
||
Document.
|
||
|
||
4. MODIFICATIONS
|
||
|
||
You may copy and distribute a Modified Version of the Document
|
||
under the conditions of sections 2 and 3 above, provided that you
|
||
release the Modified Version under precisely this License, with the
|
||
Modified Version filling the role of the Document, thus licensing
|
||
distribution and modification of the Modified Version to whoever
|
||
possesses a copy of it. In addition, you must do these things in
|
||
the Modified Version:
|
||
|
||
A. Use in the Title Page (and on the covers, if any) a title
|
||
distinct from that of the Document, and from those of previous
|
||
versions (which should, if there were any, be listed in the
|
||
History section of the Document). You may use the same title
|
||
as a previous version if the original publisher of that
|
||
version gives permission.
|
||
|
||
B. List on the Title Page, as authors, one or more persons or
|
||
entities responsible for authorship of the modifications in
|
||
the Modified Version, together with at least five of the
|
||
principal authors of the Document (all of its principal
|
||
authors, if it has fewer than five), unless they release you
|
||
from this requirement.
|
||
|
||
C. State on the Title page the name of the publisher of the
|
||
Modified Version, as the publisher.
|
||
|
||
D. Preserve all the copyright notices of the Document.
|
||
|
||
E. Add an appropriate copyright notice for your modifications
|
||
adjacent to the other copyright notices.
|
||
|
||
F. Include, immediately after the copyright notices, a license
|
||
notice giving the public permission to use the Modified
|
||
Version under the terms of this License, in the form shown in
|
||
the Addendum below.
|
||
|
||
G. Preserve in that license notice the full lists of Invariant
|
||
Sections and required Cover Texts given in the Document's
|
||
license notice.
|
||
|
||
H. Include an unaltered copy of this License.
|
||
|
||
I. Preserve the section Entitled "History", Preserve its Title,
|
||
and add to it an item stating at least the title, year, new
|
||
authors, and publisher of the Modified Version as given on the
|
||
Title Page. If there is no section Entitled "History" in the
|
||
Document, create one stating the title, year, authors, and
|
||
publisher of the Document as given on its Title Page, then add
|
||
an item describing the Modified Version as stated in the
|
||
previous sentence.
|
||
|
||
J. Preserve the network location, if any, given in the Document
|
||
for public access to a Transparent copy of the Document, and
|
||
likewise the network locations given in the Document for
|
||
previous versions it was based on. These may be placed in the
|
||
"History" section. You may omit a network location for a work
|
||
that was published at least four years before the Document
|
||
itself, or if the original publisher of the version it refers
|
||
to gives permission.
|
||
|
||
K. For any section Entitled "Acknowledgements" or "Dedications",
|
||
Preserve the Title of the section, and preserve in the section
|
||
all the substance and tone of each of the contributor
|
||
acknowledgements and/or dedications given therein.
|
||
|
||
L. Preserve all the Invariant Sections of the Document, unaltered
|
||
in their text and in their titles. Section numbers or the
|
||
equivalent are not considered part of the section titles.
|
||
|
||
M. Delete any section Entitled "Endorsements". Such a section
|
||
may not be included in the Modified Version.
|
||
|
||
N. Do not retitle any existing section to be Entitled
|
||
"Endorsements" or to conflict in title with any Invariant
|
||
Section.
|
||
|
||
O. Preserve any Warranty Disclaimers.
|
||
|
||
If the Modified Version includes new front-matter sections or
|
||
appendices that qualify as Secondary Sections and contain no
|
||
material copied from the Document, you may at your option designate
|
||
some or all of these sections as invariant. To do this, add their
|
||
titles to the list of Invariant Sections in the Modified Version's
|
||
license notice. These titles must be distinct from any other
|
||
section titles.
|
||
|
||
You may add a section Entitled "Endorsements", provided it contains
|
||
nothing but endorsements of your Modified Version by various
|
||
parties--for example, statements of peer review or that the text
|
||
has been approved by an organization as the authoritative
|
||
definition of a standard.
|
||
|
||
You may add a passage of up to five words as a Front-Cover Text,
|
||
and a passage of up to 25 words as a Back-Cover Text, to the end of
|
||
the list of Cover Texts in the Modified Version. Only one passage
|
||
of Front-Cover Text and one of Back-Cover Text may be added by (or
|
||
through arrangements made by) any one entity. If the Document
|
||
already includes a cover text for the same cover, previously added
|
||
by you or by arrangement made by the same entity you are acting on
|
||
behalf of, you may not add another; but you may replace the old
|
||
one, on explicit permission from the previous publisher that added
|
||
the old one.
|
||
|
||
The author(s) and publisher(s) of the Document do not by this
|
||
License give permission to use their names for publicity for or to
|
||
assert or imply endorsement of any Modified Version.
|
||
|
||
5. COMBINING DOCUMENTS
|
||
|
||
You may combine the Document with other documents released under
|
||
this License, under the terms defined in section 4 above for
|
||
modified versions, provided that you include in the combination all
|
||
of the Invariant Sections of all of the original documents,
|
||
unmodified, and list them all as Invariant Sections of your
|
||
combined work in its license notice, and that you preserve all
|
||
their Warranty Disclaimers.
|
||
|
||
The combined work need only contain one copy of this License, and
|
||
multiple identical Invariant Sections may be replaced with a single
|
||
copy. If there are multiple Invariant Sections with the same name
|
||
but different contents, make the title of each such section unique
|
||
by adding at the end of it, in parentheses, the name of the
|
||
original author or publisher of that section if known, or else a
|
||
unique number. Make the same adjustment to the section titles in
|
||
the list of Invariant Sections in the license notice of the
|
||
combined work.
|
||
|
||
In the combination, you must combine any sections Entitled
|
||
"History" in the various original documents, forming one section
|
||
Entitled "History"; likewise combine any sections Entitled
|
||
"Acknowledgements", and any sections Entitled "Dedications". You
|
||
must delete all sections Entitled "Endorsements."
|
||
|
||
6. COLLECTIONS OF DOCUMENTS
|
||
|
||
You may make a collection consisting of the Document and other
|
||
documents released under this License, and replace the individual
|
||
copies of this License in the various documents with a single copy
|
||
that is included in the collection, provided that you follow the
|
||
rules of this License for verbatim copying of each of the documents
|
||
in all other respects.
|
||
|
||
You may extract a single document from such a collection, and
|
||
distribute it individually under this License, provided you insert
|
||
a copy of this License into the extracted document, and follow this
|
||
License in all other respects regarding verbatim copying of that
|
||
document.
|
||
|
||
7. AGGREGATION WITH INDEPENDENT WORKS
|
||
|
||
A compilation of the Document or its derivatives with other
|
||
separate and independent documents or works, in or on a volume of a
|
||
storage or distribution medium, is called an "aggregate" if the
|
||
copyright resulting from the compilation is not used to limit the
|
||
legal rights of the compilation's users beyond what the individual
|
||
works permit. When the Document is included in an aggregate, this
|
||
License does not apply to the other works in the aggregate which
|
||
are not themselves derivative works of the Document.
|
||
|
||
If the Cover Text requirement of section 3 is applicable to these
|
||
copies of the Document, then if the Document is less than one half
|
||
of the entire aggregate, the Document's Cover Texts may be placed
|
||
on covers that bracket the Document within the aggregate, or the
|
||
electronic equivalent of covers if the Document is in electronic
|
||
form. Otherwise they must appear on printed covers that bracket
|
||
the whole aggregate.
|
||
|
||
8. TRANSLATION
|
||
|
||
Translation is considered a kind of modification, so you may
|
||
distribute translations of the Document under the terms of section
|
||
4. Replacing Invariant Sections with translations requires special
|
||
permission from their copyright holders, but you may include
|
||
translations of some or all Invariant Sections in addition to the
|
||
original versions of these Invariant Sections. You may include a
|
||
translation of this License, and all the license notices in the
|
||
Document, and any Warranty Disclaimers, provided that you also
|
||
include the original English version of this License and the
|
||
original versions of those notices and disclaimers. In case of a
|
||
disagreement between the translation and the original version of
|
||
this License or a notice or disclaimer, the original version will
|
||
prevail.
|
||
|
||
If a section in the Document is Entitled "Acknowledgements",
|
||
"Dedications", or "History", the requirement (section 4) to
|
||
Preserve its Title (section 1) will typically require changing the
|
||
actual title.
|
||
|
||
9. TERMINATION
|
||
|
||
You may not copy, modify, sublicense, or distribute the Document
|
||
except as expressly provided under this License. Any attempt
|
||
otherwise to copy, modify, sublicense, or distribute it is void,
|
||
and will automatically terminate your rights under this License.
|
||
|
||
However, if you cease all violation of this License, then your
|
||
license from a particular copyright holder is reinstated (a)
|
||
provisionally, unless and until the copyright holder explicitly and
|
||
finally terminates your license, and (b) permanently, if the
|
||
copyright holder fails to notify you of the violation by some
|
||
reasonable means prior to 60 days after the cessation.
|
||
|
||
Moreover, your license from a particular copyright holder is
|
||
reinstated permanently if the copyright holder notifies you of the
|
||
violation by some reasonable means, this is the first time you have
|
||
received notice of violation of this License (for any work) from
|
||
that copyright holder, and you cure the violation prior to 30 days
|
||
after your receipt of the notice.
|
||
|
||
Termination of your rights under this section does not terminate
|
||
the licenses of parties who have received copies or rights from you
|
||
under this License. If your rights have been terminated and not
|
||
permanently reinstated, receipt of a copy of some or all of the
|
||
same material does not give you any rights to use it.
|
||
|
||
10. FUTURE REVISIONS OF THIS LICENSE
|
||
|
||
The Free Software Foundation may publish new, revised versions of
|
||
the GNU Free Documentation License from time to time. Such new
|
||
versions will be similar in spirit to the present version, but may
|
||
differ in detail to address new problems or concerns. See
|
||
<http://www.gnu.org/copyleft/>.
|
||
|
||
Each version of the License is given a distinguishing version
|
||
number. If the Document specifies that a particular numbered
|
||
version of this License "or any later version" applies to it, you
|
||
have the option of following the terms and conditions either of
|
||
that specified version or of any later version that has been
|
||
published (not as a draft) by the Free Software Foundation. If the
|
||
Document does not specify a version number of this License, you may
|
||
choose any version ever published (not as a draft) by the Free
|
||
Software Foundation. If the Document specifies that a proxy can
|
||
decide which future versions of this License can be used, that
|
||
proxy's public statement of acceptance of a version permanently
|
||
authorizes you to choose that version for the Document.
|
||
|
||
11. RELICENSING
|
||
|
||
"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
|
||
World Wide Web server that publishes copyrightable works and also
|
||
provides prominent facilities for anybody to edit those works. A
|
||
public wiki that anybody can edit is an example of such a server.
|
||
A "Massive Multiauthor Collaboration" (or "MMC") contained in the
|
||
site means any set of copyrightable works thus published on the MMC
|
||
site.
|
||
|
||
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
|
||
license published by Creative Commons Corporation, a not-for-profit
|
||
corporation with a principal place of business in San Francisco,
|
||
California, as well as future copyleft versions of that license
|
||
published by that same organization.
|
||
|
||
"Incorporate" means to publish or republish a Document, in whole or
|
||
in part, as part of another Document.
|
||
|
||
An MMC is "eligible for relicensing" if it is licensed under this
|
||
License, and if all works that were first published under this
|
||
License somewhere other than this MMC, and subsequently
|
||
incorporated in whole or in part into the MMC, (1) had no cover
|
||
texts or invariant sections, and (2) were thus incorporated prior
|
||
to November 1, 2008.
|
||
|
||
The operator of an MMC Site may republish an MMC contained in the
|
||
site under CC-BY-SA on the same site at any time before August 1,
|
||
2009, provided the MMC is eligible for relicensing.
|
||
|
||
ADDENDUM: How to use this License for your documents
|
||
====================================================
|
||
|
||
To use this License in a document you have written, include a copy of
|
||
the License in the document and put the following copyright and license
|
||
notices just after the title page:
|
||
|
||
Copyright (C) YEAR YOUR NAME.
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.3
|
||
or any later version published by the Free Software Foundation;
|
||
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
||
Texts. A copy of the license is included in the section entitled ``GNU
|
||
Free Documentation License''.
|
||
|
||
If you have Invariant Sections, Front-Cover Texts and Back-Cover
|
||
Texts, replace the "with...Texts." line with this:
|
||
|
||
with the Invariant Sections being LIST THEIR TITLES, with
|
||
the Front-Cover Texts being LIST, and with the Back-Cover Texts
|
||
being LIST.
|
||
|
||
If you have Invariant Sections without Cover Texts, or some other
|
||
combination of the three, merge those two alternatives to suit the
|
||
situation.
|
||
|
||
If your document contains nontrivial examples of program code, we
|
||
recommend releasing these examples in parallel under your choice of free
|
||
software license, such as the GNU General Public License, to permit
|
||
their use in free software.
|
||
|
||
|
||
File: gdb.info, Node: Concept Index, Next: Command and Variable Index, Prev: GNU Free Documentation License, Up: Top
|
||
|
||
Concept Index
|
||
*************
|
||
|
||
|