This is gdb.info, produced by makeinfo version 4.8 from
|
This is gdb.info, produced by makeinfo version 4.8 from
|
../.././gdb/doc/gdb.texinfo.
|
../.././gdb/doc/gdb.texinfo.
|
|
|
INFO-DIR-SECTION Software development
|
INFO-DIR-SECTION Software development
|
START-INFO-DIR-ENTRY
|
START-INFO-DIR-ENTRY
|
* Gdb: (gdb). The GNU debugger.
|
* Gdb: (gdb). The GNU debugger.
|
END-INFO-DIR-ENTRY
|
END-INFO-DIR-ENTRY
|
|
|
This file documents the GNU debugger GDB.
|
This file documents the GNU debugger GDB.
|
|
|
This is the Ninth Edition, of `Debugging with GDB: the GNU
|
This is the Ninth Edition, of `Debugging with GDB: the GNU
|
Source-Level Debugger' for GDB Version 6.8.
|
Source-Level Debugger' for GDB Version 6.8.
|
|
|
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
1998,
|
1998,
|
1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
|
1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
|
Free Software Foundation, Inc.
|
Free Software Foundation, Inc.
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.1 or
|
under the terms of the GNU Free Documentation License, Version 1.1 or
|
any later version published by the Free Software Foundation; with the
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being "Free Software" and "Free Software Needs Free
|
Invariant Sections being "Free Software" and "Free Software Needs Free
|
Documentation", with the Front-Cover Texts being "A GNU Manual," and
|
Documentation", with the Front-Cover Texts being "A GNU Manual," and
|
with the Back-Cover Texts as in (a) below.
|
with the Back-Cover Texts as in (a) below.
|
|
|
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
|
(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
|
this GNU Manual. Buying copies from GNU Press supports the FSF in
|
developing GNU and promoting software freedom."
|
developing GNU and promoting software freedom."
|
|
|
|
|
File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions
|
File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions
|
|
|
E.2 Bytecode Descriptions
|
E.2 Bytecode Descriptions
|
=========================
|
=========================
|
|
|
Each bytecode description has the following form:
|
Each bytecode description has the following form:
|
|
|
`add' (0x02): A B => A+B
|
`add' (0x02): A B => A+B
|
Pop the top two stack items, A and B, as integers; push their sum,
|
Pop the top two stack items, A and B, as integers; push their sum,
|
as an integer.
|
as an integer.
|
|
|
|
|
In this example, `add' is the name of the bytecode, and `(0x02)' is
|
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
|
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
|
phrase "A B => A+B" shows the stack before and after the bytecode
|
executes. Beforehand, the stack must contain at least two values, A
|
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
|
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
|
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
|
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,
|
value, A+B. There may be other values on the stack below those shown,
|
but the bytecode affects only those shown.
|
but the bytecode affects only those shown.
|
|
|
Here is another example:
|
Here is another example:
|
|
|
`const8' (0x22) N: => N
|
`const8' (0x22) N: => N
|
Push the 8-bit integer constant N on the stack, without sign
|
Push the 8-bit integer constant N on the stack, without sign
|
extension.
|
extension.
|
|
|
|
|
In this example, the bytecode `const8' takes an operand N directly
|
In this example, the bytecode `const8' takes an operand N directly
|
from the bytecode stream; the operand follows the `const8' bytecode
|
from the bytecode stream; the operand follows the `const8' bytecode
|
itself. We write any such operands immediately after the name of the
|
itself. We write any such operands immediately after the name of the
|
bytecode, before the colon, and describe the exact encoding 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.
|
operand in the bytecode stream in the body of the bytecode description.
|
|
|
For the `const8' bytecode, there are no stack items given before the
|
For the `const8' bytecode, there are no stack items given before the
|
=>; this simply means that the bytecode consumes no values from the
|
=>; this simply means that the bytecode consumes no values from the
|
stack. If a bytecode consumes no values, or produces no values, the
|
stack. If a bytecode consumes no values, or produces no values, the
|
list on either side of the => may be empty.
|
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
|
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
|
an integer. If a value is written is ADDR, then the bytecode treats it
|
as an address.
|
as an address.
|
|
|
We do not fully describe the floating point operations here; although
|
We do not fully describe the floating point operations here; although
|
this design can be extended in a clean way to handle floating point
|
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
|
values, they are not of immediate interest to the customer, so we avoid
|
describing them, to save time.
|
describing them, to save time.
|
|
|
`float' (0x01): =>
|
`float' (0x01): =>
|
Prefix for floating-point bytecodes. Not implemented yet.
|
Prefix for floating-point bytecodes. Not implemented yet.
|
|
|
`add' (0x02): A B => A+B
|
`add' (0x02): A B => A+B
|
Pop two integers from the stack, and push their sum, as an integer.
|
Pop two integers from the stack, and push their sum, as an integer.
|
|
|
`sub' (0x03): A B => A-B
|
`sub' (0x03): A B => A-B
|
Pop two integers from the stack, subtract the top value from the
|
Pop two integers from the stack, subtract the top value from the
|
next-to-top value, and push the difference.
|
next-to-top value, and push the difference.
|
|
|
`mul' (0x04): A B => A*B
|
`mul' (0x04): A B => A*B
|
Pop two integers from the stack, multiply them, and push the
|
Pop two integers from the stack, multiply them, and push the
|
product on the stack. Note that, when one multiplies two N-bit
|
product on the stack. Note that, when one multiplies two N-bit
|
numbers yielding another N-bit number, it is irrelevant whether the
|
numbers yielding another N-bit number, it is irrelevant whether the
|
numbers are signed or not; the results are the same.
|
numbers are signed or not; the results are the same.
|
|
|
`div_signed' (0x05): A B => A/B
|
`div_signed' (0x05): A B => A/B
|
Pop two signed integers from the stack; divide the next-to-top
|
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
|
value by the top value, and push the quotient. If the divisor is
|
zero, terminate with an error.
|
zero, terminate with an error.
|
|
|
`div_unsigned' (0x06): A B => A/B
|
`div_unsigned' (0x06): A B => A/B
|
Pop two unsigned integers from the stack; divide the next-to-top
|
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
|
value by the top value, and push the quotient. If the divisor is
|
zero, terminate with an error.
|
zero, terminate with an error.
|
|
|
`rem_signed' (0x07): A B => A MODULO B
|
`rem_signed' (0x07): A B => A MODULO B
|
Pop two signed integers from the stack; divide the next-to-top
|
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
|
value by the top value, and push the remainder. If the divisor is
|
zero, terminate with an error.
|
zero, terminate with an error.
|
|
|
`rem_unsigned' (0x08): A B => A MODULO B
|
`rem_unsigned' (0x08): A B => A MODULO B
|
Pop two unsigned integers from the stack; divide the next-to-top
|
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
|
value by the top value, and push the remainder. If the divisor is
|
zero, terminate with an error.
|
zero, terminate with an error.
|
|
|
`lsh' (0x09): A B => A<
|
`lsh' (0x09): A B => A<
|
Pop two integers from the stack; let A be the next-to-top value,
|
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
|
and B be the top value. Shift A left by B bits, and push the
|
result.
|
result.
|
|
|
`rsh_signed' (0x0a): A B => `(signed)'A>>B
|
`rsh_signed' (0x0a): A B => `(signed)'A>>B
|
Pop two integers from the stack; let A be the next-to-top value,
|
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
|
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.
|
of the top bit at the high end, and push the result.
|
|
|
`rsh_unsigned' (0x0b): A B => A>>B
|
`rsh_unsigned' (0x0b): A B => A>>B
|
Pop two integers from the stack; let A be the next-to-top value,
|
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
|
and B be the top value. Shift A right by B bits, inserting zero
|
bits at the high end, and push the result.
|
bits at the high end, and push the result.
|
|
|
`log_not' (0x0e): A => !A
|
`log_not' (0x0e): A => !A
|
Pop an integer from the stack; if it is zero, push the value one;
|
Pop an integer from the stack; if it is zero, push the value one;
|
otherwise, push the value zero.
|
otherwise, push the value zero.
|
|
|
`bit_and' (0x0f): A B => A&B
|
`bit_and' (0x0f): A B => A&B
|
Pop two integers from the stack, and push their bitwise `and'.
|
Pop two integers from the stack, and push their bitwise `and'.
|
|
|
`bit_or' (0x10): A B => A|B
|
`bit_or' (0x10): A B => A|B
|
Pop two integers from the stack, and push their bitwise `or'.
|
Pop two integers from the stack, and push their bitwise `or'.
|
|
|
`bit_xor' (0x11): A B => A^B
|
`bit_xor' (0x11): A B => A^B
|
Pop two integers from the stack, and push their bitwise
|
Pop two integers from the stack, and push their bitwise
|
exclusive-`or'.
|
exclusive-`or'.
|
|
|
`bit_not' (0x12): A => ~A
|
`bit_not' (0x12): A => ~A
|
Pop an integer from the stack, and push its bitwise complement.
|
Pop an integer from the stack, and push its bitwise complement.
|
|
|
`equal' (0x13): A B => A=B
|
`equal' (0x13): A B => A=B
|
Pop two integers from the stack; if they are equal, push the value
|
Pop two integers from the stack; if they are equal, push the value
|
one; otherwise, push the value zero.
|
one; otherwise, push the value zero.
|
|
|
`less_signed' (0x14): A B => A
|
`less_signed' (0x14): A B => A
|
Pop two signed integers from the stack; if the next-to-top value
|
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
|
is less than the top value, push the value one; otherwise, push
|
the value zero.
|
the value zero.
|
|
|
`less_unsigned' (0x15): A B => A
|
`less_unsigned' (0x15): A B => A
|
Pop two unsigned integers from the stack; if the next-to-top value
|
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
|
is less than the top value, push the value one; otherwise, push
|
the value zero.
|
the value zero.
|
|
|
`ext' (0x16) N: A => A, sign-extended from N bits
|
`ext' (0x16) N: A => A, sign-extended from N bits
|
Pop an unsigned value from the stack; treating it as an N-bit
|
Pop an unsigned value from the stack; treating it as an N-bit
|
twos-complement value, extend it to full length. This means that
|
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
|
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
|
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
|
larger than or equal to the width of the stack elements of the
|
bytecode engine; in this case, the bytecode should have no effect.
|
bytecode engine; in this case, the bytecode should have no effect.
|
|
|
The number of source bits to preserve, N, is encoded as a single
|
The number of source bits to preserve, N, is encoded as a single
|
byte unsigned integer following the `ext' bytecode.
|
byte unsigned integer following the `ext' bytecode.
|
|
|
`zero_ext' (0x2a) N: A => A, zero-extended from N bits
|
`zero_ext' (0x2a) N: A => A, zero-extended from N bits
|
Pop an unsigned value from the stack; zero all but the bottom N
|
Pop an unsigned value from the stack; zero all but the bottom N
|
bits. This means that all bits to the left of bit N-1 (where the
|
bits. This means that all bits to the left of bit N-1 (where the
|
least significant bit is bit 0) are set to the value of bit N-1.
|
least significant bit is bit 0) are set to the value of bit N-1.
|
|
|
The number of source bits to preserve, N, is encoded as a single
|
The number of source bits to preserve, N, is encoded as a single
|
byte unsigned integer following the `zero_ext' bytecode.
|
byte unsigned integer following the `zero_ext' bytecode.
|
|
|
`ref8' (0x17): ADDR => A
|
`ref8' (0x17): ADDR => A
|
`ref16' (0x18): ADDR => A
|
`ref16' (0x18): ADDR => A
|
`ref32' (0x19): ADDR => A
|
`ref32' (0x19): ADDR => A
|
`ref64' (0x1a): ADDR => A
|
`ref64' (0x1a): ADDR => A
|
Pop an address ADDR from the stack. For bytecode `ref'N, fetch an
|
Pop an address ADDR from the stack. For bytecode `ref'N, fetch an
|
N-bit value from ADDR, using the natural target endianness. Push
|
N-bit value from ADDR, using the natural target endianness. Push
|
the fetched value as an unsigned integer.
|
the fetched value as an unsigned integer.
|
|
|
Note that ADDR may not be aligned in any particular way; the
|
Note that ADDR may not be aligned in any particular way; the
|
`refN' bytecodes should operate correctly for any address.
|
`refN' bytecodes should operate correctly for any address.
|
|
|
If attempting to access memory at ADDR would cause a processor
|
If attempting to access memory at ADDR would cause a processor
|
exception of some sort, terminate with an error.
|
exception of some sort, terminate with an error.
|
|
|
`ref_float' (0x1b): ADDR => D
|
`ref_float' (0x1b): ADDR => D
|
`ref_double' (0x1c): ADDR => D
|
`ref_double' (0x1c): ADDR => D
|
`ref_long_double' (0x1d): ADDR => D
|
`ref_long_double' (0x1d): ADDR => D
|
`l_to_d' (0x1e): A => D
|
`l_to_d' (0x1e): A => D
|
`d_to_l' (0x1f): D => A
|
`d_to_l' (0x1f): D => A
|
Not implemented yet.
|
Not implemented yet.
|
|
|
`dup' (0x28): A => A A
|
`dup' (0x28): A => A A
|
Push another copy of the stack's top element.
|
Push another copy of the stack's top element.
|
|
|
`swap' (0x2b): A B => B A
|
`swap' (0x2b): A B => B A
|
Exchange the top two items on the stack.
|
Exchange the top two items on the stack.
|
|
|
`pop' (0x29): A =>
|
`pop' (0x29): A =>
|
Discard the top value on the stack.
|
Discard the top value on the stack.
|
|
|
`if_goto' (0x20) OFFSET: A =>
|
`if_goto' (0x20) OFFSET: A =>
|
Pop an integer off the stack; if it is non-zero, branch to the
|
Pop an integer off the stack; if it is non-zero, branch to the
|
given offset in the bytecode string. Otherwise, continue to the
|
given offset in the bytecode string. Otherwise, continue to the
|
next instruction in the bytecode stream. In other words, if A is
|
next instruction in the bytecode stream. In other words, if A is
|
non-zero, set the `pc' register to `start' + OFFSET. Thus, an
|
non-zero, set the `pc' register to `start' + OFFSET. Thus, an
|
offset of zero denotes the beginning of the expression.
|
offset of zero denotes the beginning of the expression.
|
|
|
The OFFSET is stored as a sixteen-bit unsigned value, stored
|
The OFFSET is stored as a sixteen-bit unsigned value, stored
|
immediately following the `if_goto' bytecode. It is always stored
|
immediately following the `if_goto' bytecode. It is always stored
|
most significant byte first, regardless of the target's normal
|
most significant byte first, regardless of the target's normal
|
endianness. The offset is not guaranteed to fall at any particular
|
endianness. The offset is not guaranteed to fall at any particular
|
alignment within the bytecode stream; thus, on machines where
|
alignment within the bytecode stream; thus, on machines where
|
fetching a 16-bit on an unaligned address raises an exception, you
|
fetching a 16-bit on an unaligned address raises an exception, you
|
should fetch the offset one byte at a time.
|
should fetch the offset one byte at a time.
|
|
|
`goto' (0x21) OFFSET: =>
|
`goto' (0x21) OFFSET: =>
|
Branch unconditionally to OFFSET; in other words, set the `pc'
|
Branch unconditionally to OFFSET; in other words, set the `pc'
|
register to `start' + OFFSET.
|
register to `start' + OFFSET.
|
|
|
The offset is stored in the same way as for the `if_goto' bytecode.
|
The offset is stored in the same way as for the `if_goto' bytecode.
|
|
|
`const8' (0x22) N: => N
|
`const8' (0x22) N: => N
|
`const16' (0x23) N: => N
|
`const16' (0x23) N: => N
|
`const32' (0x24) N: => N
|
`const32' (0x24) N: => N
|
`const64' (0x25) N: => N
|
`const64' (0x25) N: => N
|
Push the integer constant N on the stack, without sign extension.
|
Push the integer constant N on the stack, without sign extension.
|
To produce a small negative value, push a small twos-complement
|
To produce a small negative value, push a small twos-complement
|
value, and then sign-extend it using the `ext' bytecode.
|
value, and then sign-extend it using the `ext' bytecode.
|
|
|
The constant N is stored in the appropriate number of bytes
|
The constant N is stored in the appropriate number of bytes
|
following the `const'B bytecode. The constant N is always stored
|
following the `const'B bytecode. The constant N is always stored
|
most significant byte first, regardless of the target's normal
|
most significant byte first, regardless of the target's normal
|
endianness. The constant is not guaranteed to fall at any
|
endianness. The constant is not guaranteed to fall at any
|
particular alignment within the bytecode stream; thus, on machines
|
particular alignment within the bytecode stream; thus, on machines
|
where fetching a 16-bit on an unaligned address raises an
|
where fetching a 16-bit on an unaligned address raises an
|
exception, you should fetch N one byte at a time.
|
exception, you should fetch N one byte at a time.
|
|
|
`reg' (0x26) N: => A
|
`reg' (0x26) N: => A
|
Push the value of register number N, without sign extension. The
|
Push the value of register number N, without sign extension. The
|
registers are numbered following GDB's conventions.
|
registers are numbered following GDB's conventions.
|
|
|
The register number N is encoded as a 16-bit unsigned integer
|
The register number N is encoded as a 16-bit unsigned integer
|
immediately following the `reg' bytecode. It is always stored most
|
immediately following the `reg' bytecode. It is always stored most
|
significant byte first, regardless of the target's normal
|
significant byte first, regardless of the target's normal
|
endianness. The register number is not guaranteed to fall at any
|
endianness. The register number is not guaranteed to fall at any
|
particular alignment within the bytecode stream; thus, on machines
|
particular alignment within the bytecode stream; thus, on machines
|
where fetching a 16-bit on an unaligned address raises an
|
where fetching a 16-bit on an unaligned address raises an
|
exception, you should fetch the register number one byte at a time.
|
exception, you should fetch the register number one byte at a time.
|
|
|
`trace' (0x0c): ADDR SIZE =>
|
`trace' (0x0c): ADDR SIZE =>
|
Record the contents of the SIZE bytes at ADDR in a trace buffer,
|
Record the contents of the SIZE bytes at ADDR in a trace buffer,
|
for later retrieval by GDB.
|
for later retrieval by GDB.
|
|
|
`trace_quick' (0x0d) SIZE: ADDR => ADDR
|
`trace_quick' (0x0d) SIZE: ADDR => ADDR
|
Record the contents of the SIZE bytes at ADDR in a trace buffer,
|
Record the contents of the SIZE bytes at ADDR in a trace buffer,
|
for later retrieval by GDB. SIZE is a single byte unsigned
|
for later retrieval by GDB. SIZE is a single byte unsigned
|
integer following the `trace' opcode.
|
integer following the `trace' opcode.
|
|
|
This bytecode is equivalent to the sequence `dup const8 SIZE
|
This bytecode is equivalent to the sequence `dup const8 SIZE
|
trace', but we provide it anyway to save space in bytecode strings.
|
trace', but we provide it anyway to save space in bytecode strings.
|
|
|
`trace16' (0x30) SIZE: ADDR => ADDR
|
`trace16' (0x30) SIZE: ADDR => ADDR
|
Identical to trace_quick, except that SIZE is a 16-bit big-endian
|
Identical to trace_quick, except that SIZE is a 16-bit big-endian
|
unsigned integer, not a single byte. This should probably have
|
unsigned integer, not a single byte. This should probably have
|
been named `trace_quick16', for consistency.
|
been named `trace_quick16', for consistency.
|
|
|
`end' (0x27): =>
|
`end' (0x27): =>
|
Stop executing bytecode; the result should be the top element of
|
Stop executing bytecode; the result should be the top element of
|
the stack. If the purpose of the expression was to compute an
|
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
|
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
|
the lvalue's address, and the top of the stack is the lvalue's
|
size, in bytes.
|
size, in bytes.
|
|
|
|
|
|
|
File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions
|
File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions
|
|
|
E.3 Using Agent Expressions
|
E.3 Using Agent Expressions
|
===========================
|
===========================
|
|
|
Here is a sketch of a full non-stop debugging cycle, showing how agent
|
Here is a sketch of a full non-stop debugging cycle, showing how agent
|
expressions fit into the process.
|
expressions fit into the process.
|
|
|
* The user selects trace points in the program's code at which GDB
|
* The user selects trace points in the program's code at which GDB
|
should collect data.
|
should collect data.
|
|
|
* The user specifies expressions to evaluate at each trace point.
|
* The user specifies expressions to evaluate at each trace point.
|
These expressions may denote objects in memory, in which case
|
These expressions may denote objects in memory, in which case
|
those objects' contents are recorded as the program runs, or
|
those objects' contents are recorded as the program runs, or
|
computed values, in which case the values themselves are recorded.
|
computed values, in which case the values themselves are recorded.
|
|
|
* GDB transmits the tracepoints and their associated expressions to
|
* GDB transmits the tracepoints and their associated expressions to
|
the GDB agent, running on the debugging target.
|
the GDB agent, running on the debugging target.
|
|
|
* The agent arranges to be notified when a trace point is hit. Note
|
* The agent arranges to be notified when a trace point is hit. Note
|
that, on some systems, the target operating system is completely
|
that, on some systems, the target operating system is completely
|
responsible for collecting the data; see *Note Tracing on
|
responsible for collecting the data; see *Note Tracing on
|
Symmetrix::.
|
Symmetrix::.
|
|
|
* When execution on the target reaches a trace point, the agent
|
* When execution on the target reaches a trace point, the agent
|
evaluates the expressions associated with that trace point, and
|
evaluates the expressions associated with that trace point, and
|
records the resulting values and memory ranges.
|
records the resulting values and memory ranges.
|
|
|
* Later, when the user selects a given trace event and inspects the
|
* Later, when the user selects a given trace event and inspects the
|
objects and expression values recorded, GDB talks to the agent to
|
objects and expression values recorded, GDB talks to the agent to
|
retrieve recorded data as necessary to meet the user's requests.
|
retrieve recorded data as necessary to meet the user's requests.
|
If the user asks to see an object whose contents have not been
|
If the user asks to see an object whose contents have not been
|
recorded, GDB reports an error.
|
recorded, GDB reports an error.
|
|
|
|
|
|
|
File: gdb.info, Node: Varying Target Capabilities, Next: Tracing on Symmetrix, Prev: Using Agent Expressions, Up: Agent Expressions
|
File: gdb.info, Node: Varying Target Capabilities, Next: Tracing on Symmetrix, Prev: Using Agent Expressions, Up: Agent Expressions
|
|
|
E.4 Varying Target Capabilities
|
E.4 Varying Target Capabilities
|
===============================
|
===============================
|
|
|
Some targets don't support floating-point, and some would rather not
|
Some targets don't support floating-point, and some would rather not
|
have to deal with `long long' operations. Also, different targets will
|
have to deal with `long long' operations. Also, different targets will
|
have different stack sizes, and different bytecode buffer lengths.
|
have different stack sizes, and different bytecode buffer lengths.
|
|
|
Thus, GDB needs a way to ask the target about itself. We haven't
|
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
|
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
|
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 whose length is explicit, so we can add new information to the
|
packet in future revisions of the agent, without confusing old versions
|
packet in future revisions of the agent, without confusing old versions
|
of GDB, and it should contain a version number. It should contain at
|
of GDB, and it should contain a version number. It should contain at
|
least the following information:
|
least the following information:
|
|
|
* whether floating point is supported
|
* whether floating point is supported
|
|
|
* whether `long long' is supported
|
* whether `long long' is supported
|
|
|
* maximum acceptable size of bytecode stack
|
* maximum acceptable size of bytecode stack
|
|
|
* maximum acceptable length of bytecode expressions
|
* maximum acceptable length of bytecode expressions
|
|
|
* which registers are actually available for collection
|
* which registers are actually available for collection
|
|
|
* whether the target supports disabled tracepoints
|
* whether the target supports disabled tracepoints
|
|
|
|
|
|
|
File: gdb.info, Node: Tracing on Symmetrix, Next: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions
|
File: gdb.info, Node: Tracing on Symmetrix, Next: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions
|
|
|
E.5 Tracing on Symmetrix
|
E.5 Tracing on Symmetrix
|
========================
|
========================
|
|
|
This section documents the API used by the GDB agent to collect data on
|
This section documents the API used by the GDB agent to collect data on
|
Symmetrix systems.
|
Symmetrix systems.
|
|
|
Cygnus originally implemented these tracing features to help EMC
|
Cygnus originally implemented these tracing features to help EMC
|
Corporation debug their Symmetrix high-availability disk drives. The
|
Corporation debug their Symmetrix high-availability disk drives. The
|
Symmetrix application code already includes substantial tracing
|
Symmetrix application code already includes substantial tracing
|
facilities; the GDB agent for the Symmetrix system uses those facilities
|
facilities; the GDB agent for the Symmetrix system uses those facilities
|
for its own data collection, via the API described here.
|
for its own data collection, via the API described here.
|
|
|
-- Function: DTC_RESPONSE adbg_find_memory_in_frame (FRAME_DEF *FRAME,
|
-- Function: DTC_RESPONSE adbg_find_memory_in_frame (FRAME_DEF *FRAME,
|
char *ADDRESS, char **BUFFER, unsigned int *SIZE)
|
char *ADDRESS, char **BUFFER, unsigned int *SIZE)
|
Search the trace frame FRAME for memory saved from ADDRESS. If
|
Search the trace frame FRAME for memory saved from ADDRESS. If
|
the memory is available, provide the address of the buffer holding
|
the memory is available, provide the address of the buffer holding
|
it; otherwise, provide the address of the next saved area.
|
it; otherwise, provide the address of the next saved area.
|
|
|
* If the memory at ADDRESS was saved in FRAME, set `*BUFFER' to
|
* If the memory at ADDRESS was saved in FRAME, set `*BUFFER' to
|
point to the buffer in which that memory was saved, set
|
point to the buffer in which that memory was saved, set
|
`*SIZE' to the number of bytes from ADDRESS that are saved at
|
`*SIZE' to the number of bytes from ADDRESS that are saved at
|
`*BUFFER', and return `OK_TARGET_RESPONSE'. (Clearly, in
|
`*BUFFER', and return `OK_TARGET_RESPONSE'. (Clearly, in
|
this case, the function will always set `*SIZE' to a value
|
this case, the function will always set `*SIZE' to a value
|
greater than zero.)
|
greater than zero.)
|
|
|
* If FRAME does not record any memory at ADDRESS, set `*SIZE'
|
* If FRAME does not record any memory at ADDRESS, set `*SIZE'
|
to the distance from ADDRESS to the start of the saved region
|
to the distance from ADDRESS to the start of the saved region
|
with the lowest address higher than ADDRESS. If there is no
|
with the lowest address higher than ADDRESS. If there is no
|
memory saved from any higher address, set `*SIZE' to zero.
|
memory saved from any higher address, set `*SIZE' to zero.
|
Return `NOT_FOUND_TARGET_RESPONSE'.
|
Return `NOT_FOUND_TARGET_RESPONSE'.
|
|
|
These two possibilities allow the caller to either retrieve the
|
These two possibilities allow the caller to either retrieve the
|
data, or walk the address space to the next saved area.
|
data, or walk the address space to the next saved area.
|
|
|
This function allows the GDB agent to map the regions of memory
|
This function allows the GDB agent to map the regions of memory
|
saved in a particular frame, and retrieve their contents efficiently.
|
saved in a particular frame, and retrieve their contents efficiently.
|
|
|
This function also provides a clean interface between the GDB agent
|
This function also provides a clean interface between the GDB agent
|
and the Symmetrix tracing structures, making it easier to adapt the GDB
|
and the Symmetrix tracing structures, making it easier to adapt the GDB
|
agent to future versions of the Symmetrix system, and vice versa. This
|
agent to future versions of the Symmetrix system, and vice versa. This
|
function searches all data saved in FRAME, whether the data is there at
|
function searches all data saved in FRAME, whether the data is there at
|
the request of a bytecode expression, or because it falls in one of the
|
the request of a bytecode expression, or because it falls in one of the
|
format's memory ranges, or because it was saved from the top of the
|
format's memory ranges, or because it was saved from the top of the
|
stack. EMC can arbitrarily change and enhance the tracing mechanism,
|
stack. EMC can arbitrarily change and enhance the tracing mechanism,
|
but as long as this function works properly, all collected memory is
|
but as long as this function works properly, all collected memory is
|
visible to GDB.
|
visible to GDB.
|
|
|
The function itself is straightforward to implement. A single pass
|
The function itself is straightforward to implement. A single pass
|
over the trace frame's stack area, memory ranges, and expression blocks
|
over the trace frame's stack area, memory ranges, and expression blocks
|
can yield the address of the buffer (if the requested address was
|
can yield the address of the buffer (if the requested address was
|
saved), and also note the address of the next higher range of memory,
|
saved), and also note the address of the next higher range of memory,
|
to be returned when the search fails.
|
to be returned when the search fails.
|
|
|
As an example, suppose the trace frame `f' has saved sixteen bytes
|
As an example, suppose the trace frame `f' has saved sixteen bytes
|
from address `0x8000' in a buffer at `0x1000', and thirty-two bytes
|
from address `0x8000' in a buffer at `0x1000', and thirty-two bytes
|
from address `0xc000' in a buffer at `0x1010'. Here are some sample
|
from address `0xc000' in a buffer at `0x1010'. Here are some sample
|
calls, and the effect each would have:
|
calls, and the effect each would have:
|
|
|
`adbg_find_memory_in_frame (f, (char*) 0x8000, &buffer, &size)'
|
`adbg_find_memory_in_frame (f, (char*) 0x8000, &buffer, &size)'
|
This would set `buffer' to `0x1000', set `size' to sixteen, and
|
This would set `buffer' to `0x1000', set `size' to sixteen, and
|
return `OK_TARGET_RESPONSE', since `f' saves sixteen bytes from
|
return `OK_TARGET_RESPONSE', since `f' saves sixteen bytes from
|
`0x8000' at `0x1000'.
|
`0x8000' at `0x1000'.
|
|
|
`adbg_find_memory_in_frame (f, (char *) 0x8004, &buffer, &size)'
|
`adbg_find_memory_in_frame (f, (char *) 0x8004, &buffer, &size)'
|
This would set `buffer' to `0x1004', set `size' to twelve, and
|
This would set `buffer' to `0x1004', set `size' to twelve, and
|
return `OK_TARGET_RESPONSE', since `f' saves the twelve bytes from
|
return `OK_TARGET_RESPONSE', since `f' saves the twelve bytes from
|
`0x8004' starting four bytes into the buffer at `0x1000'. This
|
`0x8004' starting four bytes into the buffer at `0x1000'. This
|
shows that request addresses may fall in the middle of saved
|
shows that request addresses may fall in the middle of saved
|
areas; the function should return the address and size of the
|
areas; the function should return the address and size of the
|
remainder of the buffer.
|
remainder of the buffer.
|
|
|
`adbg_find_memory_in_frame (f, (char *) 0x8100, &buffer, &size)'
|
`adbg_find_memory_in_frame (f, (char *) 0x8100, &buffer, &size)'
|
This would set `size' to `0x3f00' and return
|
This would set `size' to `0x3f00' and return
|
`NOT_FOUND_TARGET_RESPONSE', since there is no memory saved in `f'
|
`NOT_FOUND_TARGET_RESPONSE', since there is no memory saved in `f'
|
from the address `0x8100', and the next memory available is at
|
from the address `0x8100', and the next memory available is at
|
`0x8100 + 0x3f00', or `0xc000'. This shows that request addresses
|
`0x8100 + 0x3f00', or `0xc000'. This shows that request addresses
|
may fall outside of all saved memory ranges; the function should
|
may fall outside of all saved memory ranges; the function should
|
indicate the next saved area, if any.
|
indicate the next saved area, if any.
|
|
|
`adbg_find_memory_in_frame (f, (char *) 0x7000, &buffer, &size)'
|
`adbg_find_memory_in_frame (f, (char *) 0x7000, &buffer, &size)'
|
This would set `size' to `0x1000' and return
|
This would set `size' to `0x1000' and return
|
`NOT_FOUND_TARGET_RESPONSE', since the next saved memory is at
|
`NOT_FOUND_TARGET_RESPONSE', since the next saved memory is at
|
`0x7000 + 0x1000', or `0x8000'.
|
`0x7000 + 0x1000', or `0x8000'.
|
|
|
`adbg_find_memory_in_frame (f, (char *) 0xf000, &buffer, &size)'
|
`adbg_find_memory_in_frame (f, (char *) 0xf000, &buffer, &size)'
|
This would set `size' to zero, and return
|
This would set `size' to zero, and return
|
`NOT_FOUND_TARGET_RESPONSE'. This shows how the function tells the
|
`NOT_FOUND_TARGET_RESPONSE'. This shows how the function tells the
|
caller that no further memory ranges have been saved.
|
caller that no further memory ranges have been saved.
|
|
|
|
|
As another example, here is a function which will print out the
|
As another example, here is a function which will print out the
|
addresses of all memory saved in the trace frame `frame' on the
|
addresses of all memory saved in the trace frame `frame' on the
|
Symmetrix INLINES console:
|
Symmetrix INLINES console:
|
void
|
void
|
print_frame_addresses (FRAME_DEF *frame)
|
print_frame_addresses (FRAME_DEF *frame)
|
{
|
{
|
char *addr;
|
char *addr;
|
char *buffer;
|
char *buffer;
|
unsigned long size;
|
unsigned long size;
|
|
|
addr = 0;
|
addr = 0;
|
for (;;)
|
for (;;)
|
{
|
{
|
/* Either find out how much memory we have here, or discover
|
/* Either find out how much memory we have here, or discover
|
where the next saved region is. */
|
where the next saved region is. */
|
if (adbg_find_memory_in_frame (frame, addr, &buffer, &size)
|
if (adbg_find_memory_in_frame (frame, addr, &buffer, &size)
|
== OK_TARGET_RESPONSE)
|
== OK_TARGET_RESPONSE)
|
printp ("saved %x to %x\n", addr, addr + size);
|
printp ("saved %x to %x\n", addr, addr + size);
|
if (size == 0)
|
if (size == 0)
|
break;
|
break;
|
addr += size;
|
addr += size;
|
}
|
}
|
}
|
}
|
|
|
Note that there is not necessarily any connection between the order
|
Note that there is not necessarily any connection between the order
|
in which the data is saved in the trace frame, and the order in which
|
in which the data is saved in the trace frame, and the order in which
|
`adbg_find_memory_in_frame' will return those memory ranges. The code
|
`adbg_find_memory_in_frame' will return those memory ranges. The code
|
above will always print the saved memory regions in order of increasing
|
above will always print the saved memory regions in order of increasing
|
address, while the underlying frame structure might store the data in a
|
address, while the underlying frame structure might store the data in a
|
random order.
|
random order.
|
|
|
[[This section should cover the rest of the Symmetrix functions the
|
[[This section should cover the rest of the Symmetrix functions the
|
stub relies upon, too.]]
|
stub relies upon, too.]]
|
|
|
|
|
File: gdb.info, Node: Rationale, Prev: Tracing on Symmetrix, Up: Agent Expressions
|
File: gdb.info, Node: Rationale, Prev: Tracing on Symmetrix, Up: Agent Expressions
|
|
|
E.6 Rationale
|
E.6 Rationale
|
=============
|
=============
|
|
|
Some of the design decisions apparent above are arguable.
|
Some of the design decisions apparent above are arguable.
|
|
|
What about stack overflow/underflow?
|
What about stack overflow/underflow?
|
GDB should be able to query the target to discover its stack size.
|
GDB should be able to query the target to discover its stack size.
|
Given that information, GDB can determine at translation time
|
Given that information, GDB can determine at translation time
|
whether a given expression will overflow the stack. But this spec
|
whether a given expression will overflow the stack. But this spec
|
isn't about what kinds of error-checking GDB ought to do.
|
isn't about what kinds of error-checking GDB ought to do.
|
|
|
Why are you doing everything in LONGEST?
|
Why are you doing everything in LONGEST?
|
Speed isn't important, but agent code size is; using 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.
|
brings in a bunch of support code to do things like division, etc.
|
So this is a serious concern.
|
So this is a serious concern.
|
|
|
First, note that you don't need different bytecodes for different
|
First, note that you don't need different bytecodes for different
|
operand sizes. You can generate code without _knowing_ how big the
|
operand sizes. You can generate code without _knowing_ how big the
|
stack elements actually are on the target. If the target only
|
stack elements actually are on the target. If the target only
|
supports 32-bit ints, and you don't send any 64-bit bytecodes,
|
supports 32-bit ints, and you don't send any 64-bit bytecodes,
|
everything just works. The observation here is that the MIPS and
|
everything just works. The observation here is that the MIPS and
|
the Alpha have only fixed-size registers, and you can still get
|
the Alpha have only fixed-size registers, and you can still get
|
C's semantics even though most instructions only operate on
|
C's semantics even though most instructions only operate on
|
full-sized words. You just need to make sure everything is
|
full-sized words. You just need to make sure everything is
|
properly sign-extended at the right times. So there is no need
|
properly sign-extended at the right times. So there is no need
|
for 32- and 64-bit variants of the bytecodes. Just implement
|
for 32- and 64-bit variants of the bytecodes. Just implement
|
everything using the largest size you support.
|
everything using the largest size you support.
|
|
|
GDB should certainly check to see what sizes the target supports,
|
GDB should certainly check to see what sizes the target supports,
|
so the user can get an error earlier, rather than later. But this
|
so the user can get an error earlier, rather than later. But this
|
information is not necessary for correctness.
|
information is not necessary for correctness.
|
|
|
Why don't you have `>' or `<=' operators?
|
Why don't you have `>' or `<=' operators?
|
I want to keep the interpreter small, and we don't need them. We
|
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
|
can combine the `less_' opcodes with `log_not', and swap the order
|
of the operands, yielding all four asymmetrical comparison
|
of the operands, yielding all four asymmetrical comparison
|
operators. For example, `(x <= y)' is `! (x > y)', which is `! (y
|
operators. For example, `(x <= y)' is `! (x > y)', which is `! (y
|
< x)'.
|
< x)'.
|
|
|
Why do you have `log_not'?
|
Why do you have `log_not'?
|
Why do you have `ext'?
|
Why do you have `ext'?
|
Why do you have `zero_ext'?
|
Why do you have `zero_ext'?
|
These are all easily synthesized from other instructions, but I
|
These are all easily synthesized from other instructions, but I
|
expect them to be used frequently, and they're simple, so I
|
expect them to be used frequently, and they're simple, so I
|
include them to keep bytecode strings short.
|
include them to keep bytecode strings short.
|
|
|
`log_not' is equivalent to `const8 0 equal'; it's used in half the
|
`log_not' is equivalent to `const8 0 equal'; it's used in half the
|
relational operators.
|
relational operators.
|
|
|
`ext N' is equivalent to `const8 S-N lsh const8 S-N rsh_signed',
|
`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
|
where S is the size of the stack elements; it follows `refM' and
|
REG bytecodes when the value should be signed. See the next
|
REG bytecodes when the value should be signed. See the next
|
bulleted item.
|
bulleted item.
|
|
|
`zero_ext N' is equivalent to `constM MASK log_and'; it's used
|
`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
|
whenever we push the value of a register, because we can't assume
|
the upper bits of the register aren't garbage.
|
the upper bits of the register aren't garbage.
|
|
|
Why not have sign-extending variants of the `ref' operators?
|
Why not have sign-extending variants of the `ref' operators?
|
Because that would double the number of `ref' operators, and we
|
Because that would double the number of `ref' operators, and we
|
need the `ext' bytecode anyway for accessing bitfields.
|
need the `ext' bytecode anyway for accessing bitfields.
|
|
|
Why not have constant-address variants of the `ref' operators?
|
Why not have constant-address variants of the `ref' operators?
|
Because that would double the number of `ref' operators again, and
|
Because that would double the number of `ref' operators again, and
|
`const32 ADDRESS ref32' is only one byte longer.
|
`const32 ADDRESS ref32' is only one byte longer.
|
|
|
Why do the `refN' operators have to support unaligned fetches?
|
Why do the `refN' operators have to support unaligned fetches?
|
GDB will generate bytecode that fetches multi-byte values at
|
GDB will generate bytecode that fetches multi-byte values at
|
unaligned addresses whenever the executable's debugging
|
unaligned addresses whenever the executable's debugging
|
information tells it to. Furthermore, GDB does not know the value
|
information tells it to. Furthermore, GDB does not know the value
|
the pointer will have when GDB generates the bytecode, so it
|
the pointer will have when GDB generates the bytecode, so it
|
cannot determine whether a particular fetch will be aligned or not.
|
cannot determine whether a particular fetch will be aligned or not.
|
|
|
In particular, structure bitfields may be several bytes long, but
|
In particular, structure bitfields may be several bytes long, but
|
follow no alignment rules; members of packed structures are not
|
follow no alignment rules; members of packed structures are not
|
necessarily aligned either.
|
necessarily aligned either.
|
|
|
In general, there are many cases where unaligned references occur
|
In general, there are many cases where unaligned references occur
|
in correct C code, either at the programmer's explicit request, or
|
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
|
at the compiler's discretion. Thus, it is simpler to make the GDB
|
agent bytecodes work correctly in all circumstances than to make
|
agent bytecodes work correctly in all circumstances than to make
|
GDB guess in each case whether the compiler did the usual thing.
|
GDB guess in each case whether the compiler did the usual thing.
|
|
|
Why are there no side-effecting operators?
|
Why are there no side-effecting operators?
|
Because our current client doesn't want them? That's a cheap
|
Because our current client doesn't want them? That's a cheap
|
answer. I think the real answer is that I'm afraid of
|
answer. I think the real answer is that I'm afraid of
|
implementing function calls. We should re-visit this issue after
|
implementing function calls. We should re-visit this issue after
|
the present contract is delivered.
|
the present contract is delivered.
|
|
|
Why aren't the `goto' ops PC-relative?
|
Why aren't the `goto' ops PC-relative?
|
The interpreter has the base address around anyway for PC bounds
|
The interpreter has the base address around anyway for PC bounds
|
checking, and it seemed simpler.
|
checking, and it seemed simpler.
|
|
|
Why is there only one offset size for the `goto' ops?
|
Why is there only one offset size for the `goto' ops?
|
Offsets are currently sixteen bits. I'm not happy with this
|
Offsets are currently sixteen bits. I'm not happy with this
|
situation either:
|
situation either:
|
|
|
Suppose we have multiple branch ops with different offset sizes.
|
Suppose we have multiple branch ops with different offset sizes.
|
As I generate code left-to-right, all my jumps are forward jumps
|
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
|
(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
|
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
|
the largest offset size, or do jump relaxation on the code after I
|
generate it, which seems like a big waste of time.
|
generate it, which seems like a big waste of time.
|
|
|
I can imagine a reasonable expression being longer than 256 bytes.
|
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
|
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
|
offsets. This kind of reasoning is so bogus, but relaxation is
|
pathetic.
|
pathetic.
|
|
|
The other approach would be to generate code right-to-left. Then
|
The other approach would be to generate code right-to-left. Then
|
I'd always know my offset size. That might be fun.
|
I'd always know my offset size. That might be fun.
|
|
|
Where is the function call bytecode?
|
Where is the function call bytecode?
|
When we add side-effects, we should add this.
|
When we add side-effects, we should add this.
|
|
|
Why does the `reg' bytecode take a 16-bit register number?
|
Why does the `reg' bytecode take a 16-bit register number?
|
Intel's IA-64 architecture has 128 general-purpose registers, and
|
Intel's IA-64 architecture has 128 general-purpose registers, and
|
128 floating-point registers, and I'm sure it has some random
|
128 floating-point registers, and I'm sure it has some random
|
control registers.
|
control registers.
|
|
|
Why do we need `trace' and `trace_quick'?
|
Why do we need `trace' and `trace_quick'?
|
Because GDB needs to record all the memory contents and registers
|
Because GDB needs to record all the memory contents and registers
|
an expression touches. If the user wants to evaluate an expression
|
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
|
`x->y->z', the agent must record the values of `x' and `x->y' as
|
well as the value of `x->y->z'.
|
well as the value of `x->y->z'.
|
|
|
Don't the `trace' bytecodes make the interpreter less general?
|
Don't the `trace' bytecodes make the interpreter less general?
|
They do mean that the interpreter contains special-purpose code,
|
They do mean that the interpreter contains special-purpose code,
|
but that doesn't mean the interpreter can only be used for that
|
but that doesn't mean the interpreter can only be used for that
|
purpose. If an expression doesn't use the `trace' bytecodes, they
|
purpose. If an expression doesn't use the `trace' bytecodes, they
|
don't get in its way.
|
don't get in its way.
|
|
|
Why doesn't `trace_quick' consume its arguments the way everything else does?
|
Why doesn't `trace_quick' consume its arguments the way everything else does?
|
In general, you do want your operators to consume their arguments;
|
In general, you do want your operators to consume their arguments;
|
it's consistent, and generally reduces the amount of stack
|
it's consistent, and generally reduces the amount of stack
|
rearrangement necessary. However, `trace_quick' is a kludge to
|
rearrangement necessary. However, `trace_quick' is a kludge to
|
save space; it only exists so we needn't write `dup const8 SIZE
|
save space; it only exists so we needn't write `dup const8 SIZE
|
trace' before every memory reference. Therefore, it's okay for it
|
trace' before every memory reference. Therefore, it's okay for it
|
not to consume its arguments; it's meant for a specific context in
|
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
|
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.
|
going to have a kludge, it should be an effective kludge.
|
|
|
Why does `trace16' exist?
|
Why does `trace16' exist?
|
That opcode was added by the customer that contracted Cygnus for
|
That opcode was added by the customer that contracted Cygnus for
|
the data tracing work. I personally think it is unnecessary;
|
the data tracing work. I personally think it is unnecessary;
|
objects that large will be quite rare, so it is okay to use `dup
|
objects that large will be quite rare, so it is okay to use `dup
|
const16 SIZE trace' in those cases.
|
const16 SIZE trace' in those cases.
|
|
|
Whatever we decide to do with `trace16', we should at least leave
|
Whatever we decide to do with `trace16', we should at least leave
|
opcode 0x30 reserved, to remain compatible with the customer who
|
opcode 0x30 reserved, to remain compatible with the customer who
|
added it.
|
added it.
|
|
|
|
|
|
|
File: gdb.info, Node: Target Descriptions, Next: Copying, Prev: Agent Expressions, Up: Top
|
File: gdb.info, Node: Target Descriptions, Next: Copying, Prev: Agent Expressions, Up: Top
|
|
|
Appendix F Target Descriptions
|
Appendix F Target Descriptions
|
******************************
|
******************************
|
|
|
*Warning:* target descriptions are still under active development, and
|
*Warning:* target descriptions are still under active development, and
|
the contents and format may change between GDB releases. The format is
|
the contents and format may change between GDB releases. The format is
|
expected to stabilize in the future.
|
expected to stabilize in the future.
|
|
|
One of the challenges of using GDB to debug embedded systems is that
|
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.
|
there are so many minor variants of each processor architecture in use.
|
It is common practice for vendors to start with a standard processor
|
It is common practice for vendors to start with a standard processor
|
core -- ARM, PowerPC, or MIPS, for example -- and then make changes to
|
core -- ARM, PowerPC, or MIPS, for example -- and then make changes to
|
adapt it to a particular market niche. Some architectures have
|
adapt it to a particular market niche. Some architectures have
|
hundreds of variants, available from dozens of vendors. This leads to
|
hundreds of variants, available from dozens of vendors. This leads to
|
a number of problems:
|
a number of problems:
|
|
|
* With so many different customized processors, it is difficult for
|
* With so many different customized processors, it is difficult for
|
the GDB maintainers to keep up with the changes.
|
the GDB maintainers to keep up with the changes.
|
|
|
* Since individual variants may have short lifetimes or limited
|
* Since individual variants may have short lifetimes or limited
|
audiences, it may not be worthwhile to carry information about
|
audiences, it may not be worthwhile to carry information about
|
every variant in the GDB source tree.
|
every variant in the GDB source tree.
|
|
|
* When GDB does support the architecture of the embedded system at
|
* When GDB does support the architecture of the embedded system at
|
hand, the task of finding the correct architecture name to give the
|
hand, the task of finding the correct architecture name to give the
|
`set architecture' command can be error-prone.
|
`set architecture' command can be error-prone.
|
|
|
To address these problems, the GDB remote protocol allows a target
|
To address these problems, the GDB remote protocol allows a target
|
system to not only identify itself to GDB, but to actually describe its
|
system to not only identify itself to GDB, but to actually describe its
|
own features. This lets GDB support processor variants it has never
|
own features. This lets GDB support processor variants it has never
|
seen before -- to the extent that the descriptions are accurate, and
|
seen before -- to the extent that the descriptions are accurate, and
|
that GDB understands them.
|
that GDB understands them.
|
|
|
GDB must be linked with the Expat library to support XML target
|
GDB must be linked with the Expat library to support XML target
|
descriptions. *Note Expat::.
|
descriptions. *Note Expat::.
|
|
|
* Menu:
|
* Menu:
|
|
|
* Retrieving Descriptions:: How descriptions are fetched from a target.
|
* Retrieving Descriptions:: How descriptions are fetched from a target.
|
* Target Description Format:: The contents of a target description.
|
* Target Description Format:: The contents of a target description.
|
* Predefined Target Types:: Standard types available for target
|
* Predefined Target Types:: Standard types available for target
|
descriptions.
|
descriptions.
|
* Standard Target Features:: Features GDB knows about.
|
* Standard Target Features:: Features GDB knows about.
|
|
|
|
|
File: gdb.info, Node: Retrieving Descriptions, Next: Target Description Format, Up: Target Descriptions
|
File: gdb.info, Node: Retrieving Descriptions, Next: Target Description Format, Up: Target Descriptions
|
|
|
F.1 Retrieving Descriptions
|
F.1 Retrieving Descriptions
|
===========================
|
===========================
|
|
|
Target descriptions can be read from the target automatically, or
|
Target descriptions can be read from the target automatically, or
|
specified by the user manually. The default behavior is to read the
|
specified by the user manually. The default behavior is to read the
|
description from the target. GDB retrieves it via the remote protocol
|
description from the target. GDB retrieves it via the remote protocol
|
using `qXfer' requests (*note qXfer: General Query Packets.). The
|
using `qXfer' requests (*note qXfer: General Query Packets.). The
|
ANNEX in the `qXfer' packet will be `target.xml'. The contents of 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.xml' annex are an XML document, of the form described in *Note
|
Target Description Format::.
|
Target Description Format::.
|
|
|
Alternatively, you can specify a file to read for the target
|
Alternatively, you can specify a file to read for the target
|
description. If a file is set, the target will not be queried. The
|
description. If a file is set, the target will not be queried. The
|
commands to specify a file are:
|
commands to specify a file are:
|
|
|
`set tdesc filename PATH'
|
`set tdesc filename PATH'
|
Read the target description from PATH.
|
Read the target description from PATH.
|
|
|
`unset tdesc filename'
|
`unset tdesc filename'
|
Do not read the XML target description from a file. GDB will use
|
Do not read the XML target description from a file. GDB will use
|
the description supplied by the current target.
|
the description supplied by the current target.
|
|
|
`show tdesc filename'
|
`show tdesc filename'
|
Show the filename to read for a target description, if any.
|
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
|
File: gdb.info, Node: Target Description Format, Next: Predefined Target Types, Prev: Retrieving Descriptions, Up: Target Descriptions
|
|
|
F.2 Target Description Format
|
F.2 Target Description Format
|
=============================
|
=============================
|
|
|
A target description annex is an XML (http://www.w3.org/XML/) document
|
A target description annex is an XML (http://www.w3.org/XML/) document
|
which complies with the Document Type Definition provided in the GDB
|
which complies with the Document Type Definition provided in the GDB
|
sources in `gdb/features/gdb-target.dtd'. This means you can use
|
sources in `gdb/features/gdb-target.dtd'. This means you can use
|
generally available tools like `xmllint' to check that your feature
|
generally available tools like `xmllint' to check that your feature
|
descriptions are well-formed and valid. However, to help people
|
descriptions are well-formed and valid. However, to help people
|
unfamiliar with XML write descriptions for their targets, we also
|
unfamiliar with XML write descriptions for their targets, we also
|
describe the grammar here.
|
describe the grammar here.
|
|
|
Target descriptions can identify the architecture of the remote
|
Target descriptions can identify the architecture of the remote
|
target and (for some architectures) provide information about custom
|
target and (for some architectures) provide information about custom
|
register sets. GDB can use this information to autoconfigure for your
|
register sets. GDB can use this information to autoconfigure for your
|
target, or to warn you if you connect to an unsupported target.
|
target, or to warn you if you connect to an unsupported target.
|
|
|
Here is a simple target description:
|
Here is a simple target description:
|
|
|
|
|
i386:x86-64
|
i386:x86-64
|
|
|
|
|
This minimal description only says that the target uses the x86-64
|
This minimal description only says that the target uses the x86-64
|
architecture.
|
architecture.
|
|
|
A target description has the following overall form, with [ ] marking
|
A target description has the following overall form, with [ ] marking
|
optional elements and ... marking repeatable elements. The elements
|
optional elements and ... marking repeatable elements. The elements
|
are explained further below.
|
are explained further below.
|
|
|
|
|
|
|
|
|
[ARCHITECTURE]
|
[ARCHITECTURE]
|
[FEATURE...]
|
[FEATURE...]
|
|
|
|
|
The description is generally insensitive to whitespace and line breaks,
|
The description is generally insensitive to whitespace and line breaks,
|
under the usual common-sense rules. The XML version declaration and
|
under the usual common-sense rules. The XML version declaration and
|
document type declaration can generally be omitted (GDB does not
|
document type declaration can generally be omitted (GDB does not
|
require them), but specifying them may be useful for XML validation
|
require them), but specifying them may be useful for XML validation
|
tools. The `version' attribute for `' may also be omitted, but
|
tools. The `version' attribute for `' may also be omitted, but
|
we recommend including it; if future versions of GDB use an incompatible
|
we recommend including it; if future versions of GDB use an incompatible
|
revision of `gdb-target.dtd', they will detect and report the version
|
revision of `gdb-target.dtd', they will detect and report the version
|
mismatch.
|
mismatch.
|
|
|
F.2.1 Inclusion
|
F.2.1 Inclusion
|
---------------
|
---------------
|
|
|
It can sometimes be valuable to split a target description up into
|
It can sometimes be valuable to split a target description up into
|
several different annexes, either for organizational purposes, or to
|
several different annexes, either for organizational purposes, or to
|
share files between different possible target descriptions. You can
|
share files between different possible target descriptions. You can
|
divide a description into multiple files by replacing any element of
|
divide a description into multiple files by replacing any element of
|
the target description with an inclusion directive of the form:
|
the target description with an inclusion directive of the form:
|
|
|
|
|
|
|
When GDB encounters an element of this form, it will retrieve the named
|
When GDB encounters an element of this form, it will retrieve the named
|
XML DOCUMENT, and replace the inclusion directive with the contents of
|
XML DOCUMENT, and replace the inclusion directive with the contents of
|
that document. If the current description was read using `qXfer', then
|
that document. If the current description was read using `qXfer', then
|
so will be the included document; DOCUMENT will be interpreted as the
|
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
|
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
|
will look for DOCUMENT as a file in the same directory where it found
|
the original description.
|
the original description.
|
|
|
F.2.2 Architecture
|
F.2.2 Architecture
|
------------------
|
------------------
|
|
|
An `' element has this form:
|
An `' element has this form:
|
|
|
ARCH
|
ARCH
|
|
|
ARCH is an architecture name from the same selection accepted by
|
ARCH is an architecture name from the same selection accepted by
|
`set architecture' (*note Specifying a Debugging Target: Targets.).
|
`set architecture' (*note Specifying a Debugging Target: Targets.).
|
|
|
F.2.3 Features
|
F.2.3 Features
|
--------------
|
--------------
|
|
|
Each `' describes some logical portion of the target system.
|
Each `' describes some logical portion of the target system.
|
Features are currently used to describe available CPU registers and the
|
Features are currently used to describe available CPU registers and the
|
types of their contents. A `' element has this form:
|
types of their contents. A `' element has this form:
|
|
|
|
|
[TYPE...]
|
[TYPE...]
|
REG...
|
REG...
|
|
|
|
|
Each feature's name should be unique within the description. The name
|
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
|
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
|
the contents of that feature; if it does, the feature should have its
|
standard name. *Note Standard Target Features::.
|
standard name. *Note Standard Target Features::.
|
|
|
F.2.4 Types
|
F.2.4 Types
|
-----------
|
-----------
|
|
|
Any register's value is a collection of bits which GDB must interpret.
|
Any register's value is a collection of bits which GDB must interpret.
|
The default interpretation is a two's complement integer, but other
|
The default interpretation is a two's complement integer, but other
|
types can be requested by name in the register description. Some
|
types can be requested by name in the register description. Some
|
predefined types are provided by GDB (*note Predefined Target Types::),
|
predefined types are provided by GDB (*note Predefined Target Types::),
|
and the description can define additional composite types.
|
and the description can define additional composite types.
|
|
|
Each type element must have an `id' attribute, which gives a unique
|
Each type element must have an `id' attribute, which gives a unique
|
(within the containing `') name to the type. Types must be
|
(within the containing `') name to the type. Types must be
|
defined before they are used.
|
defined before they are used.
|
|
|
Some targets offer vector registers, which can be treated as arrays
|
Some targets offer vector registers, which can be treated as arrays
|
of scalar elements. These types are written as `' elements,
|
of scalar elements. These types are written as `' elements,
|
specifying the array element type, TYPE, and the number of elements,
|
specifying the array element type, TYPE, and the number of elements,
|
COUNT:
|
COUNT:
|
|
|
|
|
|
|
If a register's value is usefully viewed in multiple ways, define it
|
If a register's value is usefully viewed in multiple ways, define it
|
with a union type containing the useful representations. The `'
|
with a union type containing the useful representations. The `'
|
element contains one or more `' elements, each of which has a
|
element contains one or more `' elements, each of which has a
|
NAME and a TYPE:
|
NAME and a TYPE:
|
|
|
|
|
|
|
...
|
...
|
|
|
|
|
F.2.5 Registers
|
F.2.5 Registers
|
---------------
|
---------------
|
|
|
Each register is represented as an element with this form:
|
Each register is represented as an element with this form:
|
|
|
|
|
bitsize="SIZE"
|
bitsize="SIZE"
|
[regnum="NUM"]
|
[regnum="NUM"]
|
[save-restore="SAVE-RESTORE"]
|
[save-restore="SAVE-RESTORE"]
|
[type="TYPE"]
|
[type="TYPE"]
|
[group="GROUP"]/>
|
[group="GROUP"]/>
|
|
|
The components are as follows:
|
The components are as follows:
|
|
|
NAME
|
NAME
|
The register's name; it must be unique within the target
|
The register's name; it must be unique within the target
|
description.
|
description.
|
|
|
BITSIZE
|
BITSIZE
|
The register's size, in bits.
|
The register's size, in bits.
|
|
|
REGNUM
|
REGNUM
|
The register's number. If omitted, a register's number is one
|
The register's number. If omitted, a register's number is one
|
greater than that of the previous register (either in the current
|
greater than that of the previous register (either in the current
|
feature or in a preceeding feature); the first register in the
|
feature or in a preceeding feature); the first register in the
|
target description defaults to zero. This register number is used
|
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'
|
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
|
and `P' packets, and registers appear in the `g' and `G' packets
|
in order of increasing register number.
|
in order of increasing register number.
|
|
|
SAVE-RESTORE
|
SAVE-RESTORE
|
Whether the register should be preserved across inferior function
|
Whether the register should be preserved across inferior function
|
calls; this must be either `yes' or `no'. The default is `yes',
|
calls; this must be either `yes' or `no'. The default is `yes',
|
which is appropriate for most registers except for some system
|
which is appropriate for most registers except for some system
|
control registers; this is not related to the target's ABI.
|
control registers; this is not related to the target's ABI.
|
|
|
TYPE
|
TYPE
|
The type of the register. TYPE may be a predefined type, a type
|
The type of the register. TYPE may be a predefined type, a type
|
defined in the current feature, or one of the special types `int'
|
defined in the current feature, or one of the special types `int'
|
and `float'. `int' is an integer type of the correct size for
|
and `float'. `int' is an integer type of the correct size for
|
BITSIZE, and `float' is a floating point type (in the
|
BITSIZE, and `float' is a floating point type (in the
|
architecture's normal floating point format) of the correct size
|
architecture's normal floating point format) of the correct size
|
for BITSIZE. The default is `int'.
|
for BITSIZE. The default is `int'.
|
|
|
GROUP
|
GROUP
|
The register group to which this register belongs. GROUP must be
|
The register group to which this register belongs. GROUP must be
|
either `general', `float', or `vector'. If no GROUP is specified,
|
either `general', `float', or `vector'. If no GROUP is specified,
|
GDB will not display the register in `info registers'.
|
GDB will not display the register in `info registers'.
|
|
|
|
|
|
|
File: gdb.info, Node: Predefined Target Types, Next: Standard Target Features, Prev: Target Description Format, Up: Target Descriptions
|
File: gdb.info, Node: Predefined Target Types, Next: Standard Target Features, Prev: Target Description Format, Up: Target Descriptions
|
|
|
F.3 Predefined Target Types
|
F.3 Predefined Target Types
|
===========================
|
===========================
|
|
|
Type definitions in the self-description can build up composite types
|
Type definitions in the self-description can build up composite types
|
from basic building blocks, but can not define fundamental types.
|
from basic building blocks, but can not define fundamental types.
|
Instead, standard identifiers are provided by GDB for the fundamental
|
Instead, standard identifiers are provided by GDB for the fundamental
|
types. The currently supported types are:
|
types. The currently supported types are:
|
|
|
`int8'
|
`int8'
|
`int16'
|
`int16'
|
`int32'
|
`int32'
|
`int64'
|
`int64'
|
`int128'
|
`int128'
|
Signed integer types holding the specified number of bits.
|
Signed integer types holding the specified number of bits.
|
|
|
`uint8'
|
`uint8'
|
`uint16'
|
`uint16'
|
`uint32'
|
`uint32'
|
`uint64'
|
`uint64'
|
`uint128'
|
`uint128'
|
Unsigned integer types holding the specified number of bits.
|
Unsigned integer types holding the specified number of bits.
|
|
|
`code_ptr'
|
`code_ptr'
|
`data_ptr'
|
`data_ptr'
|
Pointers to unspecified code and data. The program counter and
|
Pointers to unspecified code and data. The program counter and
|
any dedicated return address register may be marked as code
|
any dedicated return address register may be marked as code
|
pointers; printing a code pointer converts it into a symbolic
|
pointers; printing a code pointer converts it into a symbolic
|
address. The stack pointer and any dedicated address registers
|
address. The stack pointer and any dedicated address registers
|
may be marked as data pointers.
|
may be marked as data pointers.
|
|
|
`ieee_single'
|
`ieee_single'
|
Single precision IEEE floating point.
|
Single precision IEEE floating point.
|
|
|
`ieee_double'
|
`ieee_double'
|
Double precision IEEE floating point.
|
Double precision IEEE floating point.
|
|
|
`arm_fpa_ext'
|
`arm_fpa_ext'
|
The 12-byte extended precision format used by ARM FPA registers.
|
The 12-byte extended precision format used by ARM FPA registers.
|
|
|
|
|
|
|
File: gdb.info, Node: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions
|
File: gdb.info, Node: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions
|
|
|
F.4 Standard Target Features
|
F.4 Standard Target Features
|
============================
|
============================
|
|
|
A target description must contain either no registers or all the
|
A target description must contain either no registers or all the
|
target's registers. If the description contains no registers, then GDB
|
target's registers. If the description contains no registers, then GDB
|
will assume a default register layout, selected based on the
|
will assume a default register layout, selected based on the
|
architecture. If the description contains any registers, the default
|
architecture. If the description contains any registers, the default
|
layout will not be used; the standard registers must be described in
|
layout will not be used; the standard registers must be described in
|
the target description, in such a way that GDB can recognize them.
|
the target description, in such a way that GDB can recognize them.
|
|
|
This is accomplished by giving specific names to feature elements
|
This is accomplished by giving specific names to feature elements
|
which contain standard registers. GDB will look for features with
|
which contain standard registers. GDB will look for features with
|
those names and verify that they contain the expected registers; if any
|
those names and verify that they contain the expected registers; if any
|
known feature is missing required registers, or if any required feature
|
known feature is missing required registers, or if any required feature
|
is missing, GDB will reject the target description. You can add
|
is missing, GDB will reject the target description. You can add
|
additional registers to any of the standard features -- GDB will
|
additional registers to any of the standard features -- GDB will
|
display them just as if they were added to an unrecognized feature.
|
display them just as if they were added to an unrecognized feature.
|
|
|
This section lists the known features and their expected contents.
|
This section lists the known features and their expected contents.
|
Sample XML documents for these features are included in the GDB source
|
Sample XML documents for these features are included in the GDB source
|
tree, in the directory `gdb/features'.
|
tree, in the directory `gdb/features'.
|
|
|
Names recognized by GDB should include the name of the company or
|
Names recognized by GDB should include the name of the company or
|
organization which selected the name, and the overall architecture to
|
organization which selected the name, and the overall architecture to
|
which the feature applies; so e.g. the feature containing ARM core
|
which the feature applies; so e.g. the feature containing ARM core
|
registers is named `org.gnu.gdb.arm.core'.
|
registers is named `org.gnu.gdb.arm.core'.
|
|
|
The names of registers are not case sensitive for the purpose of
|
The names of registers are not case sensitive for the purpose of
|
recognizing standard features, but GDB will only display registers
|
recognizing standard features, but GDB will only display registers
|
using the capitalization used in the description.
|
using the capitalization used in the description.
|
|
|
* Menu:
|
* Menu:
|
|
|
* ARM Features::
|
* ARM Features::
|
* MIPS Features::
|
* MIPS Features::
|
* M68K Features::
|
* M68K Features::
|
* PowerPC Features::
|
* PowerPC Features::
|
|
|
|
|
File: gdb.info, Node: ARM Features, Next: MIPS Features, Up: Standard Target Features
|
File: gdb.info, Node: ARM Features, Next: MIPS Features, Up: Standard Target Features
|
|
|
F.4.1 ARM Features
|
F.4.1 ARM Features
|
------------------
|
------------------
|
|
|
The `org.gnu.gdb.arm.core' feature is required for ARM targets. It
|
The `org.gnu.gdb.arm.core' feature is required for ARM targets. It
|
should contain registers `r0' through `r13', `sp', `lr', `pc', and
|
should contain registers `r0' through `r13', `sp', `lr', `pc', and
|
`cpsr'.
|
`cpsr'.
|
|
|
The `org.gnu.gdb.arm.fpa' feature is optional. If present, it
|
The `org.gnu.gdb.arm.fpa' feature is optional. If present, it
|
should contain registers `f0' through `f7' and `fps'.
|
should contain registers `f0' through `f7' and `fps'.
|
|
|
The `org.gnu.gdb.xscale.iwmmxt' feature is optional. If present, it
|
The `org.gnu.gdb.xscale.iwmmxt' feature is optional. If present, it
|
should contain at least registers `wR0' through `wR15' and `wCGR0'
|
should contain at least registers `wR0' through `wR15' and `wCGR0'
|
through `wCGR3'. The `wCID', `wCon', `wCSSF', and `wCASF' registers
|
through `wCGR3'. The `wCID', `wCon', `wCSSF', and `wCASF' registers
|
are optional.
|
are optional.
|
|
|
|
|
File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: ARM Features, Up: Standard Target Features
|
File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: ARM Features, Up: Standard Target Features
|
|
|
F.4.2 MIPS Features
|
F.4.2 MIPS Features
|
-------------------
|
-------------------
|
|
|
The `org.gnu.gdb.mips.cpu' feature is required for MIPS targets. It
|
The `org.gnu.gdb.mips.cpu' feature is required for MIPS targets. It
|
should contain registers `r0' through `r31', `lo', `hi', and `pc'.
|
should contain registers `r0' through `r31', `lo', `hi', and `pc'.
|
They may be 32-bit or 64-bit depending on the target.
|
They may be 32-bit or 64-bit depending on the target.
|
|
|
The `org.gnu.gdb.mips.cp0' feature is also required. It should
|
The `org.gnu.gdb.mips.cp0' feature is also required. It should
|
contain at least the `status', `badvaddr', and `cause' registers. They
|
contain at least the `status', `badvaddr', and `cause' registers. They
|
may be 32-bit or 64-bit depending on the target.
|
may be 32-bit or 64-bit depending on the target.
|
|
|
The `org.gnu.gdb.mips.fpu' feature is currently required, though it
|
The `org.gnu.gdb.mips.fpu' feature is currently required, though it
|
may be optional in a future version of GDB. It should contain
|
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
|
registers `f0' through `f31', `fcsr', and `fir'. They may be 32-bit or
|
64-bit depending on the target.
|
64-bit depending on the target.
|
|
|
The `org.gnu.gdb.mips.linux' feature is optional. It should contain
|
The `org.gnu.gdb.mips.linux' feature is optional. It should contain
|
a single register, `restart', which is used by the Linux kernel to
|
a single register, `restart', which is used by the Linux kernel to
|
control restartable syscalls.
|
control restartable syscalls.
|
|
|
|
|
File: gdb.info, Node: M68K Features, Next: PowerPC Features, Prev: MIPS Features, Up: Standard Target Features
|
File: gdb.info, Node: M68K Features, Next: PowerPC Features, Prev: MIPS Features, Up: Standard Target Features
|
|
|
F.4.3 M68K Features
|
F.4.3 M68K Features
|
-------------------
|
-------------------
|
|
|
``org.gnu.gdb.m68k.core''
|
``org.gnu.gdb.m68k.core''
|
``org.gnu.gdb.coldfire.core''
|
``org.gnu.gdb.coldfire.core''
|
``org.gnu.gdb.fido.core''
|
``org.gnu.gdb.fido.core''
|
One of those features must be always present. The feature that is
|
One of those features must be always present. The feature that is
|
present determines which flavor of m86k is used. The feature that
|
present determines which flavor of m86k is used. The feature that
|
is present should contain registers `d0' through `d7', `a0'
|
is present should contain registers `d0' through `d7', `a0'
|
through `a5', `fp', `sp', `ps' and `pc'.
|
through `a5', `fp', `sp', `ps' and `pc'.
|
|
|
``org.gnu.gdb.coldfire.fp''
|
``org.gnu.gdb.coldfire.fp''
|
This feature is optional. If present, it should contain registers
|
This feature is optional. If present, it should contain registers
|
`fp0' through `fp7', `fpcontrol', `fpstatus' and `fpiaddr'.
|
`fp0' through `fp7', `fpcontrol', `fpstatus' and `fpiaddr'.
|
|
|
|
|
File: gdb.info, Node: PowerPC Features, Prev: M68K Features, Up: Standard Target Features
|
File: gdb.info, Node: PowerPC Features, Prev: M68K Features, Up: Standard Target Features
|
|
|
F.4.4 PowerPC Features
|
F.4.4 PowerPC Features
|
----------------------
|
----------------------
|
|
|
The `org.gnu.gdb.power.core' feature is required for PowerPC targets.
|
The `org.gnu.gdb.power.core' feature is required for PowerPC targets.
|
It should contain registers `r0' through `r31', `pc', `msr', `cr',
|
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
|
`lr', `ctr', and `xer'. They may be 32-bit or 64-bit depending on the
|
target.
|
target.
|
|
|
The `org.gnu.gdb.power.fpu' feature is optional. It should contain
|
The `org.gnu.gdb.power.fpu' feature is optional. It should contain
|
registers `f0' through `f31' and `fpscr'.
|
registers `f0' through `f31' and `fpscr'.
|
|
|
The `org.gnu.gdb.power.altivec' feature is optional. It should
|
The `org.gnu.gdb.power.altivec' feature is optional. It should
|
contain registers `vr0' through `vr31', `vscr', and `vrsave'.
|
contain registers `vr0' through `vr31', `vscr', and `vrsave'.
|
|
|
The `org.gnu.gdb.power.spe' feature is optional. It should contain
|
The `org.gnu.gdb.power.spe' feature is optional. It should contain
|
registers `ev0h' through `ev31h', `acc', and `spefscr'. SPE targets
|
registers `ev0h' through `ev31h', `acc', and `spefscr'. SPE targets
|
should provide 32-bit registers in `org.gnu.gdb.power.core' and provide
|
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
|
the upper halves in `ev0h' through `ev31h'. GDB will combine these to
|
present registers `ev0' through `ev31' to the user.
|
present registers `ev0' through `ev31' to the user.
|
|
|
|
|
File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Target Descriptions, Up: Top
|
File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Target Descriptions, Up: Top
|
|
|
Appendix G GNU GENERAL PUBLIC LICENSE
|
Appendix G GNU GENERAL PUBLIC LICENSE
|
*************************************
|
*************************************
|
|
|
Version 2, June 1991
|
Version 2, June 1991
|
|
|
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
|
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
|
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
|
Everyone is permitted to copy and distribute verbatim copies
|
Everyone is permitted to copy and distribute verbatim copies
|
of this license document, but changing it is not allowed.
|
of this license document, but changing it is not allowed.
|
|
|
Preamble
|
Preamble
|
========
|
========
|
|
|
The licenses for most software are designed to take away your freedom
|
The licenses for most software are designed to take away your freedom
|
to share and change it. By contrast, the GNU General Public License is
|
to share and change it. By contrast, the GNU General Public License is
|
intended to guarantee your freedom to share and change free
|
intended to guarantee your freedom to share and change free
|
software--to make sure the software is free for all its users. This
|
software--to make sure the software is free for all its users. This
|
General Public License applies to most of the Free Software
|
General Public License applies to most of the Free Software
|
Foundation's software and to any other program whose authors commit to
|
Foundation's software and to any other program whose authors commit to
|
using it. (Some other Free Software Foundation software is covered by
|
using it. (Some other Free Software Foundation software is covered by
|
the GNU Library General Public License instead.) You can apply it to
|
the GNU Library General Public License instead.) You can apply it to
|
your programs, too.
|
your programs, too.
|
|
|
When we speak of free software, we are referring to freedom, not
|
When we speak of free software, we are referring to freedom, not
|
price. Our General Public Licenses are designed to make sure that you
|
price. Our General Public Licenses are designed to make sure that you
|
have the freedom to distribute copies of free software (and charge for
|
have the freedom to distribute copies of free software (and charge for
|
this service if you wish), that you receive source code or can get it
|
this service 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
|
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.
|
new free programs; and that you know you can do these things.
|
|
|
To protect your rights, we need to make restrictions that forbid
|
To protect your rights, we need to make restrictions that forbid
|
anyone to deny you these rights or to ask you to surrender the rights.
|
anyone to deny you these rights or to ask you to surrender the rights.
|
These restrictions translate to certain responsibilities for you if you
|
These restrictions translate to certain responsibilities for you if you
|
distribute copies of the software, or if you modify it.
|
distribute copies of the software, or if you modify it.
|
|
|
For example, if you distribute copies of such a program, whether
|
For example, if you distribute copies of such a program, whether
|
gratis or for a fee, you must give the recipients all the rights that
|
gratis or for a fee, you must give the recipients all the rights that
|
you have. You must make sure that they, too, receive or can get the
|
you have. 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
|
source code. And you must show them these terms so they know their
|
rights.
|
rights.
|
|
|
We protect your rights with two steps: (1) copyright the software,
|
We protect your rights with two steps: (1) copyright the software,
|
and (2) offer you this license which gives you legal permission to copy,
|
and (2) offer you this license which gives you legal permission to copy,
|
distribute and/or modify the software.
|
distribute and/or modify the software.
|
|
|
Also, for each author's protection and ours, we want to make certain
|
Also, for each author's protection and ours, we want to make certain
|
that everyone understands that there is no warranty for this free
|
that everyone understands that there is no warranty for this free
|
software. If the software is modified by someone else and passed on, we
|
software. If the software is modified by someone else and passed on, we
|
want its recipients to know that what they have is not the original, so
|
want its recipients to know that what they have is not the original, so
|
that any problems introduced by others will not reflect on the original
|
that any problems introduced by others will not reflect on the original
|
authors' reputations.
|
authors' reputations.
|
|
|
Finally, any free program is threatened constantly by software
|
Finally, any free program is threatened constantly by software
|
patents. We wish to avoid the danger that redistributors of a free
|
patents. We wish to avoid the danger that redistributors of a free
|
program will individually obtain patent licenses, in effect making the
|
program will individually obtain patent licenses, in effect making the
|
program proprietary. To prevent this, we have made it clear that any
|
program proprietary. To prevent this, we have made it clear that any
|
patent must be licensed for everyone's free use or not licensed at all.
|
patent must be licensed for everyone's free use or not licensed at all.
|
|
|
The precise terms and conditions for copying, distribution and
|
The precise terms and conditions for copying, distribution and
|
modification follow.
|
modification follow.
|
|
|
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
|
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
|
0. This License applies to any program or other work which contains a
|
0. This License applies to any program or other work which contains a
|
notice placed by the copyright holder saying it may be distributed
|
notice placed by the copyright holder saying it may be distributed
|
under the terms of this General Public License. The "Program",
|
under the terms of this General Public License. The "Program",
|
below, refers to any such program or work, and a "work based on
|
below, refers to any such program or work, and a "work based on
|
the Program" means either the Program or any derivative work under
|
the Program" means either the Program or any derivative work under
|
copyright law: that is to say, a work containing the Program or a
|
copyright law: that is to say, a work containing the Program or a
|
portion of it, either verbatim or with modifications and/or
|
portion of it, either verbatim or with modifications and/or
|
translated into another language. (Hereinafter, translation is
|
translated into another language. (Hereinafter, translation is
|
included without limitation in the term "modification".) Each
|
included without limitation in the term "modification".) Each
|
licensee is addressed as "you".
|
licensee is addressed as "you".
|
|
|
Activities other than copying, distribution and modification are
|
Activities other than copying, distribution and modification are
|
not covered by this License; they are outside its scope. The act
|
not covered by this License; they are outside its scope. The act
|
of running the Program is not restricted, and the output from the
|
of running the Program is not restricted, and the output from the
|
Program is covered only if its contents constitute a work based on
|
Program is covered only if its contents constitute a work based on
|
the Program (independent of having been made by running the
|
the Program (independent of having been made by running the
|
Program). Whether that is true depends on what the Program does.
|
Program). Whether that is true depends on what the Program does.
|
|
|
1. You may copy and distribute verbatim copies of the Program's
|
1. You may copy and distribute verbatim copies of the Program's
|
source code as you receive it, in any medium, provided that you
|
source code as you receive it, in any medium, provided that you
|
conspicuously and appropriately publish on each copy an appropriate
|
conspicuously and appropriately publish on each copy an appropriate
|
copyright notice and disclaimer of warranty; keep intact all the
|
copyright notice and disclaimer of warranty; keep intact all the
|
notices that refer to this License and to the absence of any
|
notices that refer to this License and to the absence of any
|
warranty; and give any other recipients of the Program a copy of
|
warranty; and give any other recipients of the Program a copy of
|
this License along with the Program.
|
this License along with the Program.
|
|
|
You may charge a fee for the physical act of transferring a copy,
|
You may charge a fee for the physical act of transferring a copy,
|
and you may at your option offer warranty protection in exchange
|
and you may at your option offer warranty protection in exchange
|
for a fee.
|
for a fee.
|
|
|
2. You may modify your copy or copies of the Program or any portion
|
2. You may modify your copy or copies of the Program or any portion
|
of it, thus forming a work based on the Program, and copy and
|
of it, thus forming a work based on the Program, and copy and
|
distribute such modifications or work under the terms of Section 1
|
distribute such modifications or work under the terms of Section 1
|
above, provided that you also meet all of these conditions:
|
above, provided that you also meet all of these conditions:
|
|
|
a. You must cause the modified files to carry prominent notices
|
a. You must cause the modified files to carry prominent notices
|
stating that you changed the files and the date of any change.
|
stating that you changed the files and the date of any change.
|
|
|
b. You must cause any work that you distribute or publish, that
|
b. You must cause any work that you distribute or publish, that
|
in whole or in part contains or is derived from the Program
|
in whole or in part contains or is derived from the Program
|
or any part thereof, to be licensed as a whole at no charge
|
or any part thereof, to be licensed as a whole at no charge
|
to all third parties under the terms of this License.
|
to all third parties under the terms of this License.
|
|
|
c. If the modified program normally reads commands interactively
|
c. If the modified program normally reads commands interactively
|
when run, you must cause it, when started running for such
|
when run, you must cause it, when started running for such
|
interactive use in the most ordinary way, to print or display
|
interactive use in the most ordinary way, to print or display
|
an announcement including an appropriate copyright notice and
|
an announcement including an appropriate copyright notice and
|
a notice that there is no warranty (or else, saying that you
|
a notice that there is no warranty (or else, saying that you
|
provide a warranty) and that users may redistribute the
|
provide a warranty) and that users may redistribute the
|
program under these conditions, and telling the user how to
|
program under these conditions, and telling the user how to
|
view a copy of this License. (Exception: if the Program
|
view a copy of this License. (Exception: if the Program
|
itself is interactive but does not normally print such an
|
itself is interactive but does not normally print such an
|
announcement, your work based on the Program is not required
|
announcement, your work based on the Program is not required
|
to print an announcement.)
|
to print an announcement.)
|
|
|
These requirements apply to the modified work as a whole. If
|
These requirements apply to the modified work as a whole. If
|
identifiable sections of that work are not derived from the
|
identifiable sections of that work are not derived from the
|
Program, and can be reasonably considered independent and separate
|
Program, and can be reasonably considered independent and separate
|
works in themselves, then this License, and its terms, do not
|
works in themselves, then this License, and its terms, do not
|
apply to those sections when you distribute them as separate
|
apply to those sections when you distribute them as separate
|
works. But when you distribute the same sections as part of a
|
works. But when you distribute the same sections as part of a
|
whole which is a work based on the Program, the distribution of
|
whole which is a work based on the Program, the distribution of
|
the whole must be on the terms of this License, whose permissions
|
the whole must be on the terms of this License, whose permissions
|
for other licensees extend to the entire whole, and thus to each
|
for other licensees extend to the entire whole, and thus to each
|
and every part regardless of who wrote it.
|
and every part regardless of who wrote it.
|
|
|
Thus, it is not the intent of this section to claim rights or
|
Thus, it is not the intent of this section to claim rights or
|
contest your rights to work written entirely by you; rather, the
|
contest your rights to work written entirely by you; rather, the
|
intent is to exercise the right to control the distribution of
|
intent is to exercise the right to control the distribution of
|
derivative or collective works based on the Program.
|
derivative or collective works based on the Program.
|
|
|
In addition, mere aggregation of another work not based on the
|
In addition, mere aggregation of another work not based on the
|
Program with the Program (or with a work based on the Program) on
|
Program with the Program (or with a work based on the Program) on
|
a volume of a storage or distribution medium does not bring the
|
a volume of a storage or distribution medium does not bring the
|
other work under the scope of this License.
|
other work under the scope of this License.
|
|
|
3. You may copy and distribute the Program (or a work based on it,
|
3. You may copy and distribute the Program (or a work based on it,
|
under Section 2) in object code or executable form under the terms
|
under Section 2) in object code or executable form under the terms
|
of Sections 1 and 2 above provided that you also do one of the
|
of Sections 1 and 2 above provided that you also do one of the
|
following:
|
following:
|
|
|
a. Accompany it with the complete corresponding machine-readable
|
a. Accompany it with the complete corresponding machine-readable
|
source code, which must be distributed under the terms of
|
source code, which must be distributed under the terms of
|
Sections 1 and 2 above on a medium customarily used for
|
Sections 1 and 2 above on a medium customarily used for
|
software interchange; or,
|
software interchange; or,
|
|
|
b. Accompany it with a written offer, valid for at least three
|
b. Accompany it with a written offer, valid for at least three
|
years, to give any third party, for a charge no more than your
|
years, to give any third party, for a charge no more than your
|
cost of physically performing source distribution, a complete
|
cost of physically performing source distribution, a complete
|
machine-readable copy of the corresponding source code, to be
|
machine-readable copy of the corresponding source code, to be
|
distributed under the terms of Sections 1 and 2 above on a
|
distributed under the terms of Sections 1 and 2 above on a
|
medium customarily used for software interchange; or,
|
medium customarily used for software interchange; or,
|
|
|
c. Accompany it with the information you received as to the offer
|
c. Accompany it with the information you received as to the offer
|
to distribute corresponding source code. (This alternative is
|
to distribute corresponding source code. (This alternative is
|
allowed only for noncommercial distribution and only if you
|
allowed only for noncommercial distribution and only if you
|
received the program in object code or executable form with
|
received the program in object code or executable form with
|
such an offer, in accord with Subsection b above.)
|
such an offer, in accord with Subsection b above.)
|
|
|
The source code for a work means the preferred form of the work for
|
The source code for a work means the preferred form of the work for
|
making modifications to it. For an executable work, complete
|
making modifications to it. For an executable work, complete
|
source code means all the source code for all modules it contains,
|
source code means all the source code for all modules it contains,
|
plus any associated interface definition files, plus the scripts
|
plus any associated interface definition files, plus the scripts
|
used to control compilation and installation of the executable.
|
used to control compilation and installation of the executable.
|
However, as a special exception, the source code distributed need
|
However, as a special exception, the source code distributed need
|
not include anything that is normally distributed (in either
|
not include anything that is normally distributed (in either
|
source or binary form) with the major components (compiler,
|
source or binary form) with the major components (compiler,
|
kernel, and so on) of the operating system on which the executable
|
kernel, and so on) of the operating system on which the executable
|
runs, unless that component itself accompanies the executable.
|
runs, unless that component itself accompanies the executable.
|
|
|
If distribution of executable or object code is made by offering
|
If distribution of executable or object code is made by offering
|
access to copy from a designated place, then offering equivalent
|
access to copy from a designated place, then offering equivalent
|
access to copy the source code from the same place counts as
|
access to copy the source code from the same place counts as
|
distribution of the source code, even though third parties are not
|
distribution of the source code, even though third parties are not
|
compelled to copy the source along with the object code.
|
compelled to copy the source along with the object code.
|
|
|
4. You may not copy, modify, sublicense, or distribute the Program
|
4. You may not copy, modify, sublicense, or distribute the Program
|
except as expressly provided under this License. Any attempt
|
except as expressly provided under this License. Any attempt
|
otherwise to copy, modify, sublicense or distribute the Program is
|
otherwise to copy, modify, sublicense or distribute the Program is
|
void, and will automatically terminate your rights under this
|
void, and will automatically terminate your rights under this
|
License. However, parties who have received copies, or rights,
|
License. However, parties who have received copies, or rights,
|
from you under this License will not have their licenses
|
from you under this License will not have their licenses
|
terminated so long as such parties remain in full compliance.
|
terminated so long as such parties remain in full compliance.
|
|
|
5. You are not required to accept this License, since you have not
|
5. You are not required to accept this License, since you have not
|
signed it. However, nothing else grants you permission to modify
|
signed it. However, nothing else grants you permission to modify
|
or distribute the Program or its derivative works. These actions
|
or distribute the Program or its derivative works. These actions
|
are prohibited by law if you do not accept this License.
|
are prohibited by law if you do not accept this License.
|
Therefore, by modifying or distributing the Program (or any work
|
Therefore, by modifying or distributing the Program (or any work
|
based on the Program), you indicate your acceptance of this
|
based on the Program), you indicate your acceptance of this
|
License to do so, and all its terms and conditions for copying,
|
License to do so, and all its terms and conditions for copying,
|
distributing or modifying the Program or works based on it.
|
distributing or modifying the Program or works based on it.
|
|
|
6. Each time you redistribute the Program (or any work based on the
|
6. Each time you redistribute the Program (or any work based on the
|
Program), the recipient automatically receives a license from the
|
Program), the recipient automatically receives a license from the
|
original licensor to copy, distribute or modify the Program
|
original licensor to copy, distribute or modify the Program
|
subject to these terms and conditions. You may not impose any
|
subject to these terms and conditions. You may not impose any
|
further restrictions on the recipients' exercise of the rights
|
further restrictions on the recipients' exercise of the rights
|
granted herein. You are not responsible for enforcing compliance
|
granted herein. You are not responsible for enforcing compliance
|
by third parties to this License.
|
by third parties to this License.
|
|
|
7. If, as a consequence of a court judgment or allegation of patent
|
7. If, as a consequence of a court judgment or allegation of patent
|
infringement or for any other reason (not limited to patent
|
infringement or for any other reason (not limited to patent
|
issues), conditions are imposed on you (whether by court order,
|
issues), conditions are imposed on you (whether by court order,
|
agreement or otherwise) that contradict the conditions of this
|
agreement or otherwise) that contradict the conditions of this
|
License, they do not excuse you from the conditions of this
|
License, they do not excuse you from the conditions of this
|
License. If you cannot distribute so as to satisfy simultaneously
|
License. If you cannot distribute so as to satisfy simultaneously
|
your obligations under this License and any other pertinent
|
your obligations under this License and any other pertinent
|
obligations, then as a consequence you may not distribute the
|
obligations, then as a consequence you may not distribute the
|
Program at all. For example, if a patent license would not permit
|
Program at all. For example, if a patent license would not permit
|
royalty-free redistribution of the Program by all those who
|
royalty-free redistribution of the Program by all those who
|
receive copies directly or indirectly through you, then the only
|
receive copies directly or indirectly through you, then the only
|
way you could satisfy both it and this License would be to refrain
|
way you could satisfy both it and this License would be to refrain
|
entirely from distribution of the Program.
|
entirely from distribution of the Program.
|
|
|
If any portion of this section is held invalid or unenforceable
|
If any portion of this section is held invalid or unenforceable
|
under any particular circumstance, the balance of the section is
|
under any particular circumstance, the balance of the section is
|
intended to apply and the section as a whole is intended to apply
|
intended to apply and the section as a whole is intended to apply
|
in other circumstances.
|
in other circumstances.
|
|
|
It is not the purpose of this section to induce you to infringe any
|
It is not the purpose of this section to induce you to infringe any
|
patents or other property right claims or to contest validity of
|
patents or other property right claims or to contest validity of
|
any such claims; this section has the sole purpose of protecting
|
any such claims; this section has the sole purpose of protecting
|
the integrity of the free software distribution system, which is
|
the integrity of the free software distribution system, which is
|
implemented by public license practices. Many people have made
|
implemented by public license practices. Many people have made
|
generous contributions to the wide range of software distributed
|
generous contributions to the wide range of software distributed
|
through that system in reliance on consistent application of that
|
through that system in reliance on consistent application of that
|
system; it is up to the author/donor to decide if he or she is
|
system; it is up to the author/donor to decide if he or she is
|
willing to distribute software through any other system and a
|
willing to distribute software through any other system and a
|
licensee cannot impose that choice.
|
licensee cannot impose that choice.
|
|
|
This section is intended to make thoroughly clear what is believed
|
This section is intended to make thoroughly clear what is believed
|
to be a consequence of the rest of this License.
|
to be a consequence of the rest of this License.
|
|
|
8. If the distribution and/or use of the Program is restricted in
|
8. If the distribution and/or use of the Program is restricted in
|
certain countries either by patents or by copyrighted interfaces,
|
certain countries either by patents or by copyrighted interfaces,
|
the original copyright holder who places the Program under this
|
the original copyright holder who places the Program under this
|
License may add an explicit geographical distribution limitation
|
License may add an explicit geographical distribution limitation
|
excluding those countries, so that distribution is permitted only
|
excluding those countries, so that distribution is permitted only
|
in or among countries not thus excluded. In such case, this
|
in or among countries not thus excluded. In such case, this
|
License incorporates the limitation as if written in the body of
|
License incorporates the limitation as if written in the body of
|
this License.
|
this License.
|
|
|
9. The Free Software Foundation may publish revised and/or new
|
9. The Free Software Foundation may publish revised and/or new
|
versions of the General Public License from time to time. Such
|
versions of the General Public License from time to time. Such
|
new versions will be similar in spirit to the present version, but
|
new versions will be similar in spirit to the present version, but
|
may differ in detail to address new problems or concerns.
|
may differ in detail to address new problems or concerns.
|
|
|
Each version is given a distinguishing version number. If the
|
Each version is given a distinguishing version number. If the
|
Program specifies a version number of this License which applies
|
Program specifies a version number of this License which applies
|
to it and "any later version", you have the option of following
|
to it and "any later version", you have the option of following
|
the terms and conditions either of that version or of any later
|
the terms and conditions either of that version or of any later
|
version published by the Free Software Foundation. If the Program
|
version published by the Free Software Foundation. If the Program
|
does not specify a version number of this License, you may choose
|
does not specify a version number of this License, you may choose
|
any version ever published by the Free Software Foundation.
|
any version ever published by the Free Software Foundation.
|
|
|
10. If you wish to incorporate parts of the Program into other free
|
10. If you wish to incorporate parts of the Program into other free
|
programs whose distribution conditions are different, write to the
|
programs whose distribution conditions are different, write to the
|
author to ask for permission. For software which is copyrighted
|
author to ask for permission. For software which is copyrighted
|
by the Free Software Foundation, write to the Free Software
|
by the Free Software Foundation, write to the Free Software
|
Foundation; we sometimes make exceptions for this. Our decision
|
Foundation; we sometimes make exceptions for this. Our decision
|
will be guided by the two goals of preserving the free status of
|
will be guided by the two goals of preserving the free status of
|
all derivatives of our free software and of promoting the sharing
|
all derivatives of our free software and of promoting the sharing
|
and reuse of software generally.
|
and reuse of software generally.
|
|
|
NO WARRANTY
|
NO WARRANTY
|
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
|
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
|
WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
|
WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
|
LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
|
LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
|
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
|
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
|
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
|
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
|
NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
|
NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
|
FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
|
FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
|
QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
|
QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
|
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
|
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
|
SERVICING, REPAIR OR CORRECTION.
|
SERVICING, REPAIR OR CORRECTION.
|
|
|
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
|
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
|
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
|
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
|
MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
|
MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
|
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
|
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
|
INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
|
INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
|
INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
|
INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
|
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
|
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
|
OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
|
OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
|
OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
|
OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
|
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
|
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
|
|
|
END OF TERMS AND CONDITIONS
|
END OF TERMS AND CONDITIONS
|
How to Apply These Terms to Your New Programs
|
How to Apply These Terms to Your New Programs
|
=============================================
|
=============================================
|
|
|
If you develop a new program, and you want it to be of the greatest
|
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
|
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
|
free software which everyone can redistribute and change under these
|
terms.
|
terms.
|
|
|
To do so, attach the following notices to the program. It is safest
|
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
|
to attach them to the start of each source file to most effectively
|
convey the exclusion of warranty; and each file should have at least
|
convey the exclusion of warranty; and each file should have at least
|
the "copyright" line and a pointer to where the full notice is found.
|
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.
|
ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
|
Copyright (C) YEAR NAME OF AUTHOR
|
Copyright (C) YEAR NAME OF AUTHOR
|
|
|
This program is free software; you can redistribute it and/or modify
|
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
|
it under the terms of the GNU General Public License as published by
|
the Free Software Foundation; either version 2 of the License, or
|
the Free Software Foundation; either version 2 of the License, or
|
(at your option) any later version.
|
(at your option) any later version.
|
|
|
This program is distributed in the hope that it will be useful,
|
This program is distributed in the hope that it will be useful,
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
GNU General Public License for more details.
|
GNU General Public License for more details.
|
|
|
You should have received a copy of the GNU General Public License
|
You should have received a copy of the GNU General Public License
|
along with this program; if not, write to the Free Software
|
along with this program; if not, write to the Free Software
|
Foundation, Inc., 51 Franklin Street, Fifth Floor,
|
Foundation, Inc., 51 Franklin Street, Fifth Floor,
|
Boston, MA 02110-1301, USA.
|
Boston, MA 02110-1301, USA.
|
|
|
Also add information on how to contact you by electronic and paper
|
Also add information on how to contact you by electronic and paper
|
mail.
|
mail.
|
|
|
If the program is interactive, make it output a short notice like
|
If the program is interactive, make it output a short notice like
|
this when it starts in an interactive mode:
|
this when it starts in an interactive mode:
|
|
|
Gnomovision version 69, Copyright (C) YEAR NAME OF AUTHOR
|
Gnomovision version 69, Copyright (C) YEAR NAME OF AUTHOR
|
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
|
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
|
type `show w'.
|
type `show w'.
|
This is free software, and you are welcome to redistribute it
|
This is free software, and you are welcome to redistribute it
|
under certain conditions; type `show c' for details.
|
under certain conditions; type `show c' for details.
|
|
|
The hypothetical commands `show w' and `show c' should show the
|
The hypothetical commands `show w' and `show c' should show the
|
appropriate parts of the General Public License. Of course, the
|
appropriate parts of the General Public License. Of course, the
|
commands you use may be called something other than `show w' and `show
|
commands you use may be called something other than `show w' and `show
|
c'; they could even be mouse-clicks or menu items--whatever suits your
|
c'; they could even be mouse-clicks or menu items--whatever suits your
|
program.
|
program.
|
|
|
You should also get your employer (if you work as a programmer) or
|
You should also get your employer (if you work as a programmer) or
|
your school, if any, to sign a "copyright disclaimer" for the program,
|
your school, if any, to sign a "copyright disclaimer" for the program,
|
if necessary. Here is a sample; alter the names:
|
if necessary. Here is a sample; alter the names:
|
|
|
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
|
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
|
`Gnomovision' (which makes passes at compilers) written by James Hacker.
|
`Gnomovision' (which makes passes at compilers) written by James Hacker.
|
|
|
SIGNATURE OF TY COON, 1 April 1989
|
SIGNATURE OF TY COON, 1 April 1989
|
Ty Coon, President of Vice
|
Ty Coon, President of Vice
|
|
|
This General Public License does not permit incorporating your
|
This General Public License does not permit incorporating your
|
program into proprietary programs. If your program is a subroutine
|
program into proprietary programs. If your program is a subroutine
|
library, you may consider it more useful to permit linking proprietary
|
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
|
applications with the library. If this is what you want to do, use the
|
GNU Library General Public License instead of this License.
|
GNU Library General Public License instead of this License.
|
|
|
|
|
File: gdb.info, Node: GNU Free Documentation License, Next: Index, Prev: Copying, Up: Top
|
File: gdb.info, Node: GNU Free Documentation License, Next: Index, Prev: Copying, Up: Top
|
|
|
Appendix H GNU Free Documentation License
|
Appendix H GNU Free Documentation License
|
*****************************************
|
*****************************************
|
|
|
Version 1.2, November 2002
|
Version 1.2, November 2002
|
|
|
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
|
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
|
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
|
Everyone is permitted to copy and distribute verbatim copies
|
Everyone is permitted to copy and distribute verbatim copies
|
of this license document, but changing it is not allowed.
|
of this license document, but changing it is not allowed.
|
|
|
0. PREAMBLE
|
0. PREAMBLE
|
|
|
The purpose of this License is to make a manual, textbook, or other
|
The purpose of this License is to make a manual, textbook, or other
|
functional and useful document "free" in the sense of freedom: to
|
functional and useful document "free" in the sense of freedom: to
|
assure everyone the effective freedom to copy and redistribute it,
|
assure everyone the effective freedom to copy and redistribute it,
|
with or without modifying it, either commercially or
|
with or without modifying it, either commercially or
|
noncommercially. Secondarily, this License preserves for the
|
noncommercially. Secondarily, this License preserves for the
|
author and publisher a way to get credit for their work, while not
|
author and publisher a way to get credit for their work, while not
|
being considered responsible for modifications made by others.
|
being considered responsible for modifications made by others.
|
|
|
This License is a kind of "copyleft", which means that derivative
|
This License is a kind of "copyleft", which means that derivative
|
works of the document must themselves be free in the same sense.
|
works of the document must themselves be free in the same sense.
|
It complements the GNU General Public License, which is a copyleft
|
It complements the GNU General Public License, which is a copyleft
|
license designed for free software.
|
license designed for free software.
|
|
|
We have designed this License in order to use it for manuals for
|
We have designed this License in order to use it for manuals for
|
free software, because free software needs free documentation: a
|
free software, because free software needs free documentation: a
|
free program should come with manuals providing the same freedoms
|
free program should come with manuals providing the same freedoms
|
that the software does. But this License is not limited to
|
that the software does. But this License is not limited to
|
software manuals; it can be used for any textual work, regardless
|
software manuals; it can be used for any textual work, regardless
|
of subject matter or whether it is published as a printed book.
|
of subject matter or whether it is published as a printed book.
|
We recommend this License principally for works whose purpose is
|
We recommend this License principally for works whose purpose is
|
instruction or reference.
|
instruction or reference.
|
|
|
1. APPLICABILITY AND DEFINITIONS
|
1. APPLICABILITY AND DEFINITIONS
|
|
|
This License applies to any manual or other work, in any medium,
|
This License applies to any manual or other work, in any medium,
|
that contains a notice placed by the copyright holder saying it
|
that contains a notice placed by the copyright holder saying it
|
can be distributed under the terms of this License. Such a notice
|
can be distributed under the terms of this License. Such a notice
|
grants a world-wide, royalty-free license, unlimited in duration,
|
grants a world-wide, royalty-free license, unlimited in duration,
|
to use that work under the conditions stated herein. The
|
to use that work under the conditions stated herein. The
|
"Document", below, refers to any such manual or work. Any member
|
"Document", below, refers to any such manual or work. Any member
|
of the public is a licensee, and is addressed as "you". You
|
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
|
accept the license if you copy, modify or distribute the work in a
|
way requiring permission under copyright law.
|
way requiring permission under copyright law.
|
|
|
A "Modified Version" of the Document means any work containing the
|
A "Modified Version" of the Document means any work containing the
|
Document or a portion of it, either copied verbatim, or with
|
Document or a portion of it, either copied verbatim, or with
|
modifications and/or translated into another language.
|
modifications and/or translated into another language.
|
|
|
A "Secondary Section" is a named appendix or a front-matter section
|
A "Secondary Section" is a named appendix or a front-matter section
|
of the Document that deals exclusively with the relationship of the
|
of the Document that deals exclusively with the relationship of the
|
publishers or authors of the Document to the Document's overall
|
publishers or authors of the Document to the Document's overall
|
subject (or to related matters) and contains nothing that could
|
subject (or to related matters) and contains nothing that could
|
fall directly within that overall subject. (Thus, if the Document
|
fall directly within that overall subject. (Thus, if the Document
|
is in part a textbook of mathematics, a Secondary Section may not
|
is in part a textbook of mathematics, a Secondary Section may not
|
explain any mathematics.) The relationship could be a matter of
|
explain any mathematics.) The relationship could be a matter of
|
historical connection with the subject or with related matters, or
|
historical connection with the subject or with related matters, or
|
of legal, commercial, philosophical, ethical or political position
|
of legal, commercial, philosophical, ethical or political position
|
regarding them.
|
regarding them.
|
|
|
The "Invariant Sections" are certain Secondary Sections whose
|
The "Invariant Sections" are certain Secondary Sections whose
|
titles are designated, as being those of Invariant Sections, in
|
titles are designated, as being those of Invariant Sections, in
|
the notice that says that the Document is released under this
|
the notice that says that the Document is released under this
|
License. If a section does not fit the above definition of
|
License. If a section does not fit the above definition of
|
Secondary then it is not allowed to be designated as Invariant.
|
Secondary then it is not allowed to be designated as Invariant.
|
The Document may contain zero Invariant Sections. If the Document
|
The Document may contain zero Invariant Sections. If the Document
|
does not identify any Invariant Sections then there are none.
|
does not identify any Invariant Sections then there are none.
|
|
|
The "Cover Texts" are certain short passages of text that are
|
The "Cover Texts" are certain short passages of text that are
|
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
|
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
|
that says that the Document is released under this License. A
|
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
|
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
|
be at most 25 words.
|
be at most 25 words.
|
|
|
A "Transparent" copy of the Document means a machine-readable copy,
|
A "Transparent" copy of the Document means a machine-readable copy,
|
represented in a format whose specification is available to the
|
represented in a format whose specification is available to the
|
general public, that is suitable for revising the document
|
general public, that is suitable for revising the document
|
straightforwardly with generic text editors or (for images
|
straightforwardly with generic text editors or (for images
|
composed of pixels) generic paint programs or (for drawings) some
|
composed of pixels) generic paint programs or (for drawings) some
|
widely available drawing editor, and that is suitable for input to
|
widely available drawing editor, and that is suitable for input to
|
text formatters or for automatic translation to a variety of
|
text formatters or for automatic translation to a variety of
|
formats suitable for input to text formatters. A copy made in an
|
formats suitable for input to text formatters. A copy made in an
|
otherwise Transparent file format whose markup, or absence of
|
otherwise Transparent file format whose markup, or absence of
|
markup, has been arranged to thwart or discourage subsequent
|
markup, has been arranged to thwart or discourage subsequent
|
modification by readers is not Transparent. An image format is
|
modification by readers is not Transparent. An image format is
|
not Transparent if used for any substantial amount of text. A
|
not Transparent if used for any substantial amount of text. A
|
copy that is not "Transparent" is called "Opaque".
|
copy that is not "Transparent" is called "Opaque".
|
|
|
Examples of suitable formats for Transparent copies include plain
|
Examples of suitable formats for Transparent copies include plain
|
ASCII without markup, Texinfo input format, LaTeX input format,
|
ASCII without markup, Texinfo input format, LaTeX input format,
|
SGML or XML using a publicly available DTD, and
|
SGML or XML using a publicly available DTD, and
|
standard-conforming simple HTML, PostScript or PDF designed for
|
standard-conforming simple HTML, PostScript or PDF designed for
|
human modification. Examples of transparent image formats include
|
human modification. Examples of transparent image formats include
|
PNG, XCF and JPG. Opaque formats include proprietary formats that
|
PNG, XCF and JPG. Opaque formats include proprietary formats that
|
can be read and edited only by proprietary word processors, SGML or
|
can be read and edited only by proprietary word processors, SGML or
|
XML for which the DTD and/or processing tools are not generally
|
XML for which the DTD and/or processing tools are not generally
|
available, and the machine-generated HTML, PostScript or PDF
|
available, and the machine-generated HTML, PostScript or PDF
|
produced by some word processors for output purposes only.
|
produced by some word processors for output purposes only.
|
|
|
The "Title Page" means, for a printed book, the title page itself,
|
The "Title Page" means, for a printed book, the title page itself,
|
plus such following pages as are needed to hold, legibly, the
|
plus such following pages as are needed to hold, legibly, the
|
material this License requires to appear in the title page. For
|
material this License requires to appear in the title page. For
|
works in formats which do not have any title page as such, "Title
|
works in formats which do not have any title page as such, "Title
|
Page" means the text near the most prominent appearance of the
|
Page" means the text near the most prominent appearance of the
|
work's title, preceding the beginning of the body of the text.
|
work's title, preceding the beginning of the body of the text.
|
|
|
A section "Entitled XYZ" means a named subunit of the Document
|
A section "Entitled XYZ" means a named subunit of the Document
|
whose title either is precisely XYZ or contains XYZ in parentheses
|
whose title either is precisely XYZ or contains XYZ in parentheses
|
following text that translates XYZ in another language. (Here XYZ
|
following text that translates XYZ in another language. (Here XYZ
|
stands for a specific section name mentioned below, such as
|
stands for a specific section name mentioned below, such as
|
"Acknowledgements", "Dedications", "Endorsements", or "History".)
|
"Acknowledgements", "Dedications", "Endorsements", or "History".)
|
To "Preserve the Title" of such a section when you modify the
|
To "Preserve the Title" of such a section when you modify the
|
Document means that it remains a section "Entitled XYZ" according
|
Document means that it remains a section "Entitled XYZ" according
|
to this definition.
|
to this definition.
|
|
|
The Document may include Warranty Disclaimers next to the notice
|
The Document may include Warranty Disclaimers next to the notice
|
which states that this License applies to the Document. These
|
which states that this License applies to the Document. These
|
Warranty Disclaimers are considered to be included by reference in
|
Warranty Disclaimers are considered to be included by reference in
|
this License, but only as regards disclaiming warranties: any other
|
this License, but only as regards disclaiming warranties: any other
|
implication that these Warranty Disclaimers may have is void and
|
implication that these Warranty Disclaimers may have is void and
|
has no effect on the meaning of this License.
|
has no effect on the meaning of this License.
|
|
|
2. VERBATIM COPYING
|
2. VERBATIM COPYING
|
|
|
You may copy and distribute the Document in any medium, either
|
You may copy and distribute the Document in any medium, either
|
commercially or noncommercially, provided that this License, the
|
commercially or noncommercially, provided that this License, the
|
copyright notices, and the license notice saying this License
|
copyright notices, and the license notice saying this License
|
applies to the Document are reproduced in all copies, and that you
|
applies to the Document are reproduced in all copies, and that you
|
add no other conditions whatsoever to those of this License. You
|
add no other conditions whatsoever to those of this License. You
|
may not use technical measures to obstruct or control the reading
|
may not use technical measures to obstruct or control the reading
|
or further copying of the copies you make or distribute. However,
|
or further copying of the copies you make or distribute. However,
|
you may accept compensation in exchange for copies. If you
|
you may accept compensation in exchange for copies. If you
|
distribute a large enough number of copies you must also follow
|
distribute a large enough number of copies you must also follow
|
the conditions in section 3.
|
the conditions in section 3.
|
|
|
You may also lend copies, under the same conditions stated above,
|
You may also lend copies, under the same conditions stated above,
|
and you may publicly display copies.
|
and you may publicly display copies.
|
|
|
3. COPYING IN QUANTITY
|
3. COPYING IN QUANTITY
|
|
|
If you publish printed copies (or copies in media that commonly
|
If you publish printed copies (or copies in media that commonly
|
have printed covers) of the Document, numbering more than 100, and
|
have printed covers) of the Document, numbering more than 100, and
|
the Document's license notice requires Cover Texts, you must
|
the Document's license notice requires Cover Texts, you must
|
enclose the copies in covers that carry, clearly and legibly, all
|
enclose the copies in covers that carry, clearly and legibly, all
|
these Cover Texts: Front-Cover Texts on the front cover, and
|
these Cover Texts: Front-Cover Texts on the front cover, and
|
Back-Cover Texts on the back cover. Both covers must also clearly
|
Back-Cover Texts on the back cover. Both covers must also clearly
|
and legibly identify you as the publisher of these copies. The
|
and legibly identify you as the publisher of these copies. The
|
front cover must present the full title with all words of the
|
front cover must present the full title with all words of the
|
title equally prominent and visible. You may add other material
|
title equally prominent and visible. You may add other material
|
on the covers in addition. Copying with changes limited to the
|
on the covers in addition. Copying with changes limited to the
|
covers, as long as they preserve the title of the Document and
|
covers, as long as they preserve the title of the Document and
|
satisfy these conditions, can be treated as verbatim copying in
|
satisfy these conditions, can be treated as verbatim copying in
|
other respects.
|
other respects.
|
|
|
If the required texts for either cover are too voluminous to fit
|
If the required texts for either cover are too voluminous to fit
|
legibly, you should put the first ones listed (as many as fit
|
legibly, you should put the first ones listed (as many as fit
|
reasonably) on the actual cover, and continue the rest onto
|
reasonably) on the actual cover, and continue the rest onto
|
adjacent pages.
|
adjacent pages.
|
|
|
If you publish or distribute Opaque copies of the Document
|
If you publish or distribute Opaque copies of the Document
|
numbering more than 100, you must either include a
|
numbering more than 100, you must either include a
|
machine-readable Transparent copy along with each Opaque copy, or
|
machine-readable Transparent copy along with each Opaque copy, or
|
state in or with each Opaque copy a computer-network location from
|
state in or with each Opaque copy a computer-network location from
|
which the general network-using public has access to download
|
which the general network-using public has access to download
|
using public-standard network protocols a complete Transparent
|
using public-standard network protocols a complete Transparent
|
copy of the Document, free of added material. If you use the
|
copy of the Document, free of added material. If you use the
|
latter option, you must take reasonably prudent steps, when you
|
latter option, you must take reasonably prudent steps, when you
|
begin distribution of Opaque copies in quantity, to ensure that
|
begin distribution of Opaque copies in quantity, to ensure that
|
this Transparent copy will remain thus accessible at the stated
|
this Transparent copy will remain thus accessible at the stated
|
location until at least one year after the last time you
|
location until at least one year after the last time you
|
distribute an Opaque copy (directly or through your agents or
|
distribute an Opaque copy (directly or through your agents or
|
retailers) of that edition to the public.
|
retailers) of that edition to the public.
|
|
|
It is requested, but not required, that you contact the authors of
|
It is requested, but not required, that you contact the authors of
|
the Document well before redistributing any large number of
|
the Document well before redistributing any large number of
|
copies, to give them a chance to provide you with an updated
|
copies, to give them a chance to provide you with an updated
|
version of the Document.
|
version of the Document.
|
|
|
4. MODIFICATIONS
|
4. MODIFICATIONS
|
|
|
You may copy and distribute a Modified Version of the Document
|
You may copy and distribute a Modified Version of the Document
|
under the conditions of sections 2 and 3 above, provided that you
|
under the conditions of sections 2 and 3 above, provided that you
|
release the Modified Version under precisely this License, with
|
release the Modified Version under precisely this License, with
|
the Modified Version filling the role of the Document, thus
|
the Modified Version filling the role of the Document, thus
|
licensing distribution and modification of the Modified Version to
|
licensing distribution and modification of the Modified Version to
|
whoever possesses a copy of it. In addition, you must do these
|
whoever possesses a copy of it. In addition, you must do these
|
things in the Modified Version:
|
things in the Modified Version:
|
|
|
A. Use in the Title Page (and on the covers, if any) a title
|
A. Use in the Title Page (and on the covers, if any) a title
|
distinct from that of the Document, and from those of
|
distinct from that of the Document, and from those of
|
previous versions (which should, if there were any, be listed
|
previous versions (which should, if there were any, be listed
|
in the History section of the Document). You may use the
|
in the History section of the Document). You may use the
|
same title as a previous version if the original publisher of
|
same title as a previous version if the original publisher of
|
that version gives permission.
|
that version gives permission.
|
|
|
B. List on the Title Page, as authors, one or more persons or
|
B. List on the Title Page, as authors, one or more persons or
|
entities responsible for authorship of the modifications in
|
entities responsible for authorship of the modifications in
|
the Modified Version, together with at least five of the
|
the Modified Version, together with at least five of the
|
principal authors of the Document (all of its principal
|
principal authors of the Document (all of its principal
|
authors, if it has fewer than five), unless they release you
|
authors, if it has fewer than five), unless they release you
|
from this requirement.
|
from this requirement.
|
|
|
C. State on the Title page the name of the publisher of the
|
C. State on the Title page the name of the publisher of the
|
Modified Version, as the publisher.
|
Modified Version, as the publisher.
|
|
|
D. Preserve all the copyright notices of the Document.
|
D. Preserve all the copyright notices of the Document.
|
|
|
E. Add an appropriate copyright notice for your modifications
|
E. Add an appropriate copyright notice for your modifications
|
adjacent to the other copyright notices.
|
adjacent to the other copyright notices.
|
|
|
F. Include, immediately after the copyright notices, a license
|
F. Include, immediately after the copyright notices, a license
|
notice giving the public permission to use the Modified
|
notice giving the public permission to use the Modified
|
Version under the terms of this License, in the form shown in
|
Version under the terms of this License, in the form shown in
|
the Addendum below.
|
the Addendum below.
|
|
|
G. Preserve in that license notice the full lists of Invariant
|
G. Preserve in that license notice the full lists of Invariant
|
Sections and required Cover Texts given in the Document's
|
Sections and required Cover Texts given in the Document's
|
license notice.
|
license notice.
|
|
|
H. Include an unaltered copy of this License.
|
H. Include an unaltered copy of this License.
|
|
|
I. Preserve the section Entitled "History", Preserve its Title,
|
I. Preserve the section Entitled "History", Preserve its Title,
|
and add to it an item stating at least the title, year, new
|
and add to it an item stating at least the title, year, new
|
authors, and publisher of the Modified Version as given on
|
authors, and publisher of the Modified Version as given on
|
the Title Page. If there is no section Entitled "History" in
|
the Title Page. If there is no section Entitled "History" in
|
the Document, create one stating the title, year, authors,
|
the Document, create one stating the title, year, authors,
|
and publisher of the Document as given on its Title Page,
|
and publisher of the Document as given on its Title Page,
|
then add an item describing the Modified Version as stated in
|
then add an item describing the Modified Version as stated in
|
the previous sentence.
|
the previous sentence.
|
|
|
J. Preserve the network location, if any, given in the Document
|
J. Preserve the network location, if any, given in the Document
|
for public access to a Transparent copy of the Document, and
|
for public access to a Transparent copy of the Document, and
|
likewise the network locations given in the Document for
|
likewise the network locations given in the Document for
|
previous versions it was based on. These may be placed in
|
previous versions it was based on. These may be placed in
|
the "History" section. You may omit a network location for a
|
the "History" section. You may omit a network location for a
|
work that was published at least four years before the
|
work that was published at least four years before the
|
Document itself, or if the original publisher of the version
|
Document itself, or if the original publisher of the version
|
it refers to gives permission.
|
it refers to gives permission.
|
|
|
K. For any section Entitled "Acknowledgements" or "Dedications",
|
K. For any section Entitled "Acknowledgements" or "Dedications",
|
Preserve the Title of the section, and preserve in the
|
Preserve the Title of the section, and preserve in the
|
section all the substance and tone of each of the contributor
|
section all the substance and tone of each of the contributor
|
acknowledgements and/or dedications given therein.
|
acknowledgements and/or dedications given therein.
|
|
|
L. Preserve all the Invariant Sections of the Document,
|
L. Preserve all the Invariant Sections of the Document,
|
unaltered in their text and in their titles. Section numbers
|
unaltered in their text and in their titles. Section numbers
|
or the equivalent are not considered part of the section
|
or the equivalent are not considered part of the section
|
titles.
|
titles.
|
|
|
M. Delete any section Entitled "Endorsements". Such a section
|
M. Delete any section Entitled "Endorsements". Such a section
|
may not be included in the Modified Version.
|
may not be included in the Modified Version.
|
|
|
N. Do not retitle any existing section to be Entitled
|
N. Do not retitle any existing section to be Entitled
|
"Endorsements" or to conflict in title with any Invariant
|
"Endorsements" or to conflict in title with any Invariant
|
Section.
|
Section.
|
|
|
O. Preserve any Warranty Disclaimers.
|
O. Preserve any Warranty Disclaimers.
|
|
|
If the Modified Version includes new front-matter sections or
|
If the Modified Version includes new front-matter sections or
|
appendices that qualify as Secondary Sections and contain no
|
appendices that qualify as Secondary Sections and contain no
|
material copied from the Document, you may at your option
|
material copied from the Document, you may at your option
|
designate some or all of these sections as invariant. To do this,
|
designate some or all of these sections as invariant. To do this,
|
add their titles to the list of Invariant Sections in the Modified
|
add their titles to the list of Invariant Sections in the Modified
|
Version's license notice. These titles must be distinct from any
|
Version's license notice. These titles must be distinct from any
|
other section titles.
|
other section titles.
|
|
|
You may add a section Entitled "Endorsements", provided it contains
|
You may add a section Entitled "Endorsements", provided it contains
|
nothing but endorsements of your Modified Version by various
|
nothing but endorsements of your Modified Version by various
|
parties--for example, statements of peer review or that the text
|
parties--for example, statements of peer review or that the text
|
has been approved by an organization as the authoritative
|
has been approved by an organization as the authoritative
|
definition of a standard.
|
definition of a standard.
|
|
|
You may add a passage of up to five words as a Front-Cover Text,
|
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
|
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
|
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
|
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
|
added by (or through arrangements made by) any one entity. If the
|
Document already includes a cover text for the same cover,
|
Document already includes a cover text for the same cover,
|
previously added by you or by arrangement made by the same entity
|
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
|
you are acting on behalf of, you may not add another; but you may
|
replace the old one, on explicit permission from the previous
|
replace the old one, on explicit permission from the previous
|
publisher that added the old one.
|
publisher that added the old one.
|
|
|
The author(s) and publisher(s) of the Document do not by this
|
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
|
License give permission to use their names for publicity for or to
|
assert or imply endorsement of any Modified Version.
|
assert or imply endorsement of any Modified Version.
|
|
|
5. COMBINING DOCUMENTS
|
5. COMBINING DOCUMENTS
|
|
|
You may combine the Document with other documents released under
|
You may combine the Document with other documents released under
|
this License, under the terms defined in section 4 above for
|
this License, under the terms defined in section 4 above for
|
modified versions, provided that you include in the combination
|
modified versions, provided that you include in the combination
|
all of the Invariant Sections of all of the original documents,
|
all of the Invariant Sections of all of the original documents,
|
unmodified, and list them all as Invariant Sections of your
|
unmodified, and list them all as Invariant Sections of your
|
combined work in its license notice, and that you preserve all
|
combined work in its license notice, and that you preserve all
|
their Warranty Disclaimers.
|
their Warranty Disclaimers.
|
|
|
The combined work need only contain one copy of this License, and
|
The combined work need only contain one copy of this License, and
|
multiple identical Invariant Sections may be replaced with a single
|
multiple identical Invariant Sections may be replaced with a single
|
copy. If there are multiple Invariant Sections with the same name
|
copy. If there are multiple Invariant Sections with the same name
|
but different contents, make the title of each such section unique
|
but different contents, make the title of each such section unique
|
by adding at the end of it, in parentheses, the name of the
|
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
|
original author or publisher of that section if known, or else a
|
unique number. Make the same adjustment to the section titles in
|
unique number. Make the same adjustment to the section titles in
|
the list of Invariant Sections in the license notice of the
|
the list of Invariant Sections in the license notice of the
|
combined work.
|
combined work.
|
|
|
In the combination, you must combine any sections Entitled
|
In the combination, you must combine any sections Entitled
|
"History" in the various original documents, forming one section
|
"History" in the various original documents, forming one section
|
Entitled "History"; likewise combine any sections Entitled
|
Entitled "History"; likewise combine any sections Entitled
|
"Acknowledgements", and any sections Entitled "Dedications". You
|
"Acknowledgements", and any sections Entitled "Dedications". You
|
must delete all sections Entitled "Endorsements."
|
must delete all sections Entitled "Endorsements."
|
|
|
6. COLLECTIONS OF DOCUMENTS
|
6. COLLECTIONS OF DOCUMENTS
|
|
|
You may make a collection consisting of the Document and other
|
You may make a collection consisting of the Document and other
|
documents released under this License, and replace the individual
|
documents released under this License, and replace the individual
|
copies of this License in the various documents with a single copy
|
copies of this License in the various documents with a single copy
|
that is included in the collection, provided that you follow the
|
that is included in the collection, provided that you follow the
|
rules of this License for verbatim copying of each of the
|
rules of this License for verbatim copying of each of the
|
documents in all other respects.
|
documents in all other respects.
|
|
|
You may extract a single document from such a collection, and
|
You may extract a single document from such a collection, and
|
distribute it individually under this License, provided you insert
|
distribute it individually under this License, provided you insert
|
a copy of this License into the extracted document, and follow
|
a copy of this License into the extracted document, and follow
|
this License in all other respects regarding verbatim copying of
|
this License in all other respects regarding verbatim copying of
|
that document.
|
that document.
|
|
|
7. AGGREGATION WITH INDEPENDENT WORKS
|
7. AGGREGATION WITH INDEPENDENT WORKS
|
|
|
A compilation of the Document or its derivatives with other
|
A compilation of the Document or its derivatives with other
|
separate and independent documents or works, in or on a volume of
|
separate and independent documents or works, in or on a volume of
|
a storage or distribution medium, is called an "aggregate" if the
|
a storage or distribution medium, is called an "aggregate" if the
|
copyright resulting from the compilation is not used to limit the
|
copyright resulting from the compilation is not used to limit the
|
legal rights of the compilation's users beyond what the individual
|
legal rights of the compilation's users beyond what the individual
|
works permit. When the Document is included in an aggregate, this
|
works permit. When the Document is included in an aggregate, this
|
License does not apply to the other works in the aggregate which
|
License does not apply to the other works in the aggregate which
|
are not themselves derivative works of the Document.
|
are not themselves derivative works of the Document.
|
|
|
If the Cover Text requirement of section 3 is applicable to these
|
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
|
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
|
of the entire aggregate, the Document's Cover Texts may be placed
|
on covers that bracket the Document within the aggregate, or the
|
on covers that bracket the Document within the aggregate, or the
|
electronic equivalent of covers if the Document is in electronic
|
electronic equivalent of covers if the Document is in electronic
|
form. Otherwise they must appear on printed covers that bracket
|
form. Otherwise they must appear on printed covers that bracket
|
the whole aggregate.
|
the whole aggregate.
|
|
|
8. TRANSLATION
|
8. TRANSLATION
|
|
|
Translation is considered a kind of modification, so you may
|
Translation is considered a kind of modification, so you may
|
distribute translations of the Document under the terms of section
|
distribute translations of the Document under the terms of section
|
4. Replacing Invariant Sections with translations requires special
|
4. Replacing Invariant Sections with translations requires special
|
permission from their copyright holders, but you may include
|
permission from their copyright holders, but you may include
|
translations of some or all Invariant Sections in addition to the
|
translations of some or all Invariant Sections in addition to the
|
original versions of these Invariant Sections. You may include a
|
original versions of these Invariant Sections. You may include a
|
translation of this License, and all the license notices in the
|
translation of this License, and all the license notices in the
|
Document, and any Warranty Disclaimers, provided that you also
|
Document, and any Warranty Disclaimers, provided that you also
|
include the original English version of this License and the
|
include the original English version of this License and the
|
original versions of those notices and disclaimers. In case of a
|
original versions of those notices and disclaimers. In case of a
|
disagreement between the translation and the original version of
|
disagreement between the translation and the original version of
|
this License or a notice or disclaimer, the original version will
|
this License or a notice or disclaimer, the original version will
|
prevail.
|
prevail.
|
|
|
If a section in the Document is Entitled "Acknowledgements",
|
If a section in the Document is Entitled "Acknowledgements",
|
"Dedications", or "History", the requirement (section 4) to
|
"Dedications", or "History", the requirement (section 4) to
|
Preserve its Title (section 1) will typically require changing the
|
Preserve its Title (section 1) will typically require changing the
|
actual title.
|
actual title.
|
|
|
9. TERMINATION
|
9. TERMINATION
|
|
|
You may not copy, modify, sublicense, or distribute the Document
|
You may not copy, modify, sublicense, or distribute the Document
|
except as expressly provided for under this License. Any other
|
except as expressly provided for under this License. Any other
|
attempt to copy, modify, sublicense or distribute the Document is
|
attempt to copy, modify, sublicense or distribute the Document is
|
void, and will automatically terminate your rights under this
|
void, and will automatically terminate your rights under this
|
License. However, parties who have received copies, or rights,
|
License. However, parties who have received copies, or rights,
|
from you under this License will not have their licenses
|
from you under this License will not have their licenses
|
terminated so long as such parties remain in full compliance.
|
terminated so long as such parties remain in full compliance.
|
|
|
10. FUTURE REVISIONS OF THIS LICENSE
|
10. FUTURE REVISIONS OF THIS LICENSE
|
|
|
The Free Software Foundation may publish new, revised versions of
|
The Free Software Foundation may publish new, revised versions of
|
the GNU Free Documentation License from time to time. Such new
|
the GNU Free Documentation License from time to time. Such new
|
versions will be similar in spirit to the present version, but may
|
versions will be similar in spirit to the present version, but may
|
differ in detail to address new problems or concerns. See
|
differ in detail to address new problems or concerns. See
|
`http://www.gnu.org/copyleft/'.
|
`http://www.gnu.org/copyleft/'.
|
|
|
Each version of the License is given a distinguishing version
|
Each version of the License is given a distinguishing version
|
number. If the Document specifies that a particular numbered
|
number. If the Document specifies that a particular numbered
|
version of this License "or any later version" applies to it, you
|
version of this License "or any later version" applies to it, you
|
have the option of following the terms and conditions either of
|
have the option of following the terms and conditions either of
|
that specified version or of any later version that has been
|
that specified version or of any later version that has been
|
published (not as a draft) by the Free Software Foundation. If
|
published (not as a draft) by the Free Software Foundation. If
|
the Document does not specify a version number of this License,
|
the Document does not specify a version number of this License,
|
you may choose any version ever published (not as a draft) by the
|
you may choose any version ever published (not as a draft) by the
|
Free Software Foundation.
|
Free Software Foundation.
|
|
|
H.1 ADDENDUM: How to use this License for your documents
|
H.1 ADDENDUM: How to use this License for your documents
|
========================================================
|
========================================================
|
|
|
To use this License in a document you have written, include a copy of
|
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
|
the License in the document and put the following copyright and license
|
notices just after the title page:
|
notices just after the title page:
|
|
|
Copyright (C) YEAR YOUR NAME.
|
Copyright (C) YEAR YOUR NAME.
|
Permission is granted to copy, distribute and/or modify this document
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.2
|
under the terms of the GNU Free Documentation License, Version 1.2
|
or any later version published by the Free Software Foundation;
|
or any later version published by the Free Software Foundation;
|
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
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
|
Texts. A copy of the license is included in the section entitled ``GNU
|
Free Documentation License''.
|
Free Documentation License''.
|
|
|
If you have Invariant Sections, Front-Cover Texts and Back-Cover
|
If you have Invariant Sections, Front-Cover Texts and Back-Cover
|
Texts, replace the "with...Texts." line with this:
|
Texts, replace the "with...Texts." line with this:
|
|
|
with the Invariant Sections being LIST THEIR TITLES, with
|
with the Invariant Sections being LIST THEIR TITLES, with
|
the Front-Cover Texts being LIST, and with the Back-Cover Texts
|
the Front-Cover Texts being LIST, and with the Back-Cover Texts
|
being LIST.
|
being LIST.
|
|
|
If you have Invariant Sections without Cover Texts, or some other
|
If you have Invariant Sections without Cover Texts, or some other
|
combination of the three, merge those two alternatives to suit the
|
combination of the three, merge those two alternatives to suit the
|
situation.
|
situation.
|
|
|
If your document contains nontrivial examples of program code, we
|
If your document contains nontrivial examples of program code, we
|
recommend releasing these examples in parallel under your choice of
|
recommend releasing these examples in parallel under your choice of
|
free software license, such as the GNU General Public License, to
|
free software license, such as the GNU General Public License, to
|
permit their use in free software.
|
permit their use in free software.
|
|
|
|
|
File: gdb.info, Node: Index, Prev: GNU Free Documentation License, Up: Top
|
File: gdb.info, Node: Index, Prev: GNU Free Documentation License, Up: Top
|
|
|
Index
|
Index
|
*****
|
*****
|
|
|
|