| This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo. |
| |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * Gdb: (gdb). The GNU debugger. |
| END-INFO-DIR-ENTRY |
| |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, |
| 2010 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| |
| This file documents the GNU debugger GDB. |
| |
| This is the Ninth Edition, of `Debugging with GDB: the GNU |
| Source-Level Debugger' for GDB (GDB) Version 7.2. |
| |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, |
| 2010 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| |
| |
| File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions |
| |
| E.2 Bytecode Descriptions |
| ========================= |
| |
| Each bytecode description has the following form: |
| |
| `add' (0x02): A B => A+B |
| Pop the top two stack items, A and B, as integers; push their sum, |
| as an integer. |
| |
| |
| In this example, `add' is the name of the bytecode, and `(0x02)' is |
| the one-byte value used to encode the bytecode, in hexadecimal. The |
| phrase "A B => A+B" shows the stack before and after the bytecode |
| executes. Beforehand, the stack must contain at least two values, A |
| and B; since the top of the stack is to the right, B is on the top of |
| the stack, and A is underneath it. After execution, the bytecode will |
| have popped A and B from the stack, and replaced them with a single |
| value, A+B. There may be other values on the stack below those shown, |
| but the bytecode affects only those shown. |
| |
| Here is another example: |
| |
| `const8' (0x22) N: => N |
| Push the 8-bit integer constant N on the stack, without sign |
| extension. |
| |
| |
| In this example, the bytecode `const8' takes an operand N directly |
| from the bytecode stream; the operand follows the `const8' bytecode |
| itself. We write any such operands immediately after the name of the |
| bytecode, before the colon, and describe the exact encoding of the |
| operand in the bytecode stream in the body of the bytecode description. |
| |
| For the `const8' bytecode, there are no stack items given before the |
| =>; this simply means that the bytecode consumes no values from the |
| stack. If a bytecode consumes no values, or produces no values, the |
| list on either side of the => may be empty. |
| |
| If a value is written as A, B, or N, then the bytecode treats it as |
| an integer. If a value is written is ADDR, then the bytecode treats it |
| as an address. |
| |
| We do not fully describe the floating point operations here; although |
| this design can be extended in a clean way to handle floating point |
| values, they are not of immediate interest to the customer, so we avoid |
| describing them, to save time. |
| |
| `float' (0x01): => |
| Prefix for floating-point bytecodes. Not implemented yet. |
| |
| `add' (0x02): A B => A+B |
| Pop two integers from the stack, and push their sum, as an integer. |
| |
| `sub' (0x03): A B => A-B |
| Pop two integers from the stack, subtract the top value from the |
| next-to-top value, and push the difference. |
| |
| `mul' (0x04): A B => A*B |
| Pop two integers from the stack, multiply them, and push the |
| product on the stack. Note that, when one multiplies two N-bit |
| numbers yielding another N-bit number, it is irrelevant whether the |
| numbers are signed or not; the results are the same. |
| |
| `div_signed' (0x05): A B => A/B |
| Pop two signed integers from the stack; divide the next-to-top |
| value by the top value, and push the quotient. If the divisor is |
| zero, terminate with an error. |
| |
| `div_unsigned' (0x06): A B => A/B |
| Pop two unsigned integers from the stack; divide the next-to-top |
| value by the top value, and push the quotient. If the divisor is |
| zero, terminate with an error. |
| |
| `rem_signed' (0x07): A B => A MODULO B |
| Pop two signed integers from the stack; divide the next-to-top |
| value by the top value, and push the remainder. If the divisor is |
| zero, terminate with an error. |
| |
| `rem_unsigned' (0x08): A B => A MODULO B |
| Pop two unsigned integers from the stack; divide the next-to-top |
| value by the top value, and push the remainder. If the divisor is |
| zero, terminate with an error. |
| |
| `lsh' (0x09): A B => A<<B |
| Pop two integers from the stack; let A be the next-to-top value, |
| and B be the top value. Shift A left by B bits, and push the |
| result. |
| |
| `rsh_signed' (0x0a): A B => `(signed)'A>>B |
| Pop two integers from the stack; let A be the next-to-top value, |
| and B be the top value. Shift A right by B bits, inserting copies |
| of the top bit at the high end, and push the result. |
| |
| `rsh_unsigned' (0x0b): A B => A>>B |
| Pop two integers from the stack; let A be the next-to-top value, |
| and B be the top value. Shift A right by B bits, inserting zero |
| bits at the high end, and push the result. |
| |
| `log_not' (0x0e): A => !A |
| Pop an integer from the stack; if it is zero, push the value one; |
| otherwise, push the value zero. |
| |
| `bit_and' (0x0f): A B => A&B |
| Pop two integers from the stack, and push their bitwise `and'. |
| |
| `bit_or' (0x10): A B => A|B |
| Pop two integers from the stack, and push their bitwise `or'. |
| |
| `bit_xor' (0x11): A B => A^B |
| Pop two integers from the stack, and push their bitwise |
| exclusive-`or'. |
| |
| `bit_not' (0x12): A => ~A |
| Pop an integer from the stack, and push its bitwise complement. |
| |
| `equal' (0x13): A B => A=B |
| Pop two integers from the stack; if they are equal, push the value |
| one; otherwise, push the value zero. |
| |
| `less_signed' (0x14): A B => A<B |
| Pop two signed integers from the stack; if the next-to-top value |
| is less than the top value, push the value one; otherwise, push |
| the value zero. |
| |
| `less_unsigned' (0x15): A B => A<B |
| Pop two unsigned integers from the stack; if the next-to-top value |
| is less than the top value, push the value one; otherwise, push |
| the value zero. |
| |
| `ext' (0x16) N: A => A, sign-extended from N bits |
| Pop an unsigned value from the stack; treating it as an N-bit |
| twos-complement value, extend it to full length. This means that |
| all bits to the left of bit N-1 (where the least significant bit |
| is bit 0) are set to the value of bit N-1. Note that N may be |
| larger than or equal to the width of the stack elements of the |
| bytecode engine; in this case, the bytecode should have no effect. |
| |
| The number of source bits to preserve, N, is encoded as a single |
| byte unsigned integer following the `ext' bytecode. |
| |
| `zero_ext' (0x2a) N: A => A, zero-extended from N bits |
| Pop an unsigned value from the stack; zero all but the bottom N |
| bits. This means that all bits to the left of bit N-1 (where the |
| least significant bit is bit 0) are set to the value of bit N-1. |
| |
| The number of source bits to preserve, N, is encoded as a single |
| byte unsigned integer following the `zero_ext' bytecode. |
| |
| `ref8' (0x17): ADDR => A |
| `ref16' (0x18): ADDR => A |
| `ref32' (0x19): ADDR => A |
| `ref64' (0x1a): ADDR => A |
| Pop an address ADDR from the stack. For bytecode `ref'N, fetch an |
| N-bit value from ADDR, using the natural target endianness. Push |
| the fetched value as an unsigned integer. |
| |
| Note that ADDR may not be aligned in any particular way; the |
| `refN' bytecodes should operate correctly for any address. |
| |
| If attempting to access memory at ADDR would cause a processor |
| exception of some sort, terminate with an error. |
| |
| `ref_float' (0x1b): ADDR => D |
| `ref_double' (0x1c): ADDR => D |
| `ref_long_double' (0x1d): ADDR => D |
| `l_to_d' (0x1e): A => D |
| `d_to_l' (0x1f): D => A |
| Not implemented yet. |
| |
| `dup' (0x28): A => A A |
| Push another copy of the stack's top element. |
| |
| `swap' (0x2b): A B => B A |
| Exchange the top two items on the stack. |
| |
| `pop' (0x29): A => |
| Discard the top value on the stack. |
| |
| `if_goto' (0x20) OFFSET: A => |
| Pop an integer off the stack; if it is non-zero, branch to the |
| given offset in the bytecode string. Otherwise, continue to the |
| next instruction in the bytecode stream. In other words, if A is |
| non-zero, set the `pc' register to `start' + OFFSET. Thus, an |
| offset of zero denotes the beginning of the expression. |
| |
| The OFFSET is stored as a sixteen-bit unsigned value, stored |
| immediately following the `if_goto' bytecode. It is always stored |
| most significant byte first, regardless of the target's normal |
| endianness. The offset is not guaranteed to fall at any particular |
| alignment within the bytecode stream; thus, on machines where |
| fetching a 16-bit on an unaligned address raises an exception, you |
| should fetch the offset one byte at a time. |
| |
| `goto' (0x21) OFFSET: => |
| Branch unconditionally to OFFSET; in other words, set the `pc' |
| register to `start' + OFFSET. |
| |
| The offset is stored in the same way as for the `if_goto' bytecode. |
| |
| `const8' (0x22) N: => N |
| `const16' (0x23) N: => N |
| `const32' (0x24) N: => N |
| `const64' (0x25) N: => N |
| Push the integer constant N on the stack, without sign extension. |
| To produce a small negative value, push a small twos-complement |
| value, and then sign-extend it using the `ext' bytecode. |
| |
| The constant N is stored in the appropriate number of bytes |
| following the `const'B bytecode. The constant N is always stored |
| most significant byte first, regardless of the target's normal |
| endianness. The constant is not guaranteed to fall at any |
| particular alignment within the bytecode stream; thus, on machines |
| where fetching a 16-bit on an unaligned address raises an |
| exception, you should fetch N one byte at a time. |
| |
| `reg' (0x26) N: => A |
| Push the value of register number N, without sign extension. The |
| registers are numbered following GDB's conventions. |
| |
| The register number N is encoded as a 16-bit unsigned integer |
| immediately following the `reg' bytecode. It is always stored most |
| significant byte first, regardless of the target's normal |
| endianness. The register number is not guaranteed to fall at any |
| particular alignment within the bytecode stream; thus, on machines |
| where fetching a 16-bit on an unaligned address raises an |
| exception, you should fetch the register number one byte at a time. |
| |
| `getv' (0x2c) N: => V |
| Push the value of trace state variable number N, without sign |
| extension. |
| |
| The variable number N is encoded as a 16-bit unsigned integer |
| immediately following the `getv' bytecode. It is always stored |
| most significant byte first, regardless of the target's normal |
| endianness. The variable number is not guaranteed to fall at any |
| particular alignment within the bytecode stream; thus, on machines |
| where fetching a 16-bit on an unaligned address raises an |
| exception, you should fetch the register number one byte at a time. |
| |
| `setv' (0x2d) N: => V |
| Set trace state variable number N to the value found on the top of |
| the stack. The stack is unchanged, so that the value is readily |
| available if the assignment is part of a larger expression. The |
| handling of N is as described for `getv'. |
| |
| `trace' (0x0c): ADDR SIZE => |
| Record the contents of the SIZE bytes at ADDR in a trace buffer, |
| for later retrieval by GDB. |
| |
| `trace_quick' (0x0d) SIZE: ADDR => ADDR |
| Record the contents of the SIZE bytes at ADDR in a trace buffer, |
| for later retrieval by GDB. SIZE is a single byte unsigned |
| integer following the `trace' opcode. |
| |
| This bytecode is equivalent to the sequence `dup const8 SIZE |
| trace', but we provide it anyway to save space in bytecode strings. |
| |
| `trace16' (0x30) SIZE: ADDR => ADDR |
| Identical to trace_quick, except that SIZE is a 16-bit big-endian |
| unsigned integer, not a single byte. This should probably have |
| been named `trace_quick16', for consistency. |
| |
| `tracev' (0x2e) N: => A |
| Record the value of trace state variable number N in the trace |
| buffer. The handling of N is as described for `getv'. |
| |
| `end' (0x27): => |
| Stop executing bytecode; the result should be the top element of |
| the stack. If the purpose of the expression was to compute an |
| lvalue or a range of memory, then the next-to-top of the stack is |
| the lvalue's address, and the top of the stack is the lvalue's |
| size, in bytes. |
| |
| |
| |
| File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions |
| |
| E.3 Using Agent Expressions |
| =========================== |
| |
| Agent expressions can be used in several different ways by GDB, and the |
| debugger can generate different bytecode sequences as appropriate. |
| |
| One possibility is to do expression evaluation on the target rather |
| than the host, such as for the conditional of a conditional tracepoint. |
| In such a case, GDB compiles the source expression into a bytecode |
| sequence that simply gets values from registers or memory, does |
| arithmetic, and returns a result. |
| |
| Another way to use agent expressions is for tracepoint data |
| collection. GDB generates a different bytecode sequence for |
| collection; in addition to bytecodes that do the calculation, GDB adds |
| `trace' bytecodes to save the pieces of memory that were used. |
| |
| * The user selects trace points in the program's code at which GDB |
| should collect data. |
| |
| * The user specifies expressions to evaluate at each trace point. |
| These expressions may denote objects in memory, in which case |
| those objects' contents are recorded as the program runs, or |
| computed values, in which case the values themselves are recorded. |
| |
| * GDB transmits the tracepoints and their associated expressions to |
| the GDB agent, running on the debugging target. |
| |
| * The agent arranges to be notified when a trace point is hit. |
| |
| * When execution on the target reaches a trace point, the agent |
| evaluates the expressions associated with that trace point, and |
| records the resulting values and memory ranges. |
| |
| * Later, when the user selects a given trace event and inspects the |
| objects and expression values recorded, GDB talks to the agent to |
| retrieve recorded data as necessary to meet the user's requests. |
| If the user asks to see an object whose contents have not been |
| recorded, GDB reports an error. |
| |
| |
| |
| File: gdb.info, Node: Varying Target Capabilities, Next: Rationale, Prev: Using Agent Expressions, Up: Agent Expressions |
| |
| E.4 Varying Target Capabilities |
| =============================== |
| |
| Some targets don't support floating-point, and some would rather not |
| have to deal with `long long' operations. Also, different targets will |
| have different stack sizes, and different bytecode buffer lengths. |
| |
| Thus, GDB needs a way to ask the target about itself. We haven't |
| worked out the details yet, but in general, GDB should be able to send |
| the target a packet asking it to describe itself. The reply should be a |
| packet whose length is explicit, so we can add new information to the |
| packet in future revisions of the agent, without confusing old versions |
| of GDB, and it should contain a version number. It should contain at |
| least the following information: |
| |
| * whether floating point is supported |
| |
| * whether `long long' is supported |
| |
| * maximum acceptable size of bytecode stack |
| |
| * maximum acceptable length of bytecode expressions |
| |
| * which registers are actually available for collection |
| |
| * whether the target supports disabled tracepoints |
| |
| |
| |
| File: gdb.info, Node: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions |
| |
| E.5 Rationale |
| ============= |
| |
| Some of the design decisions apparent above are arguable. |
| |
| What about stack overflow/underflow? |
| GDB should be able to query the target to discover its stack size. |
| Given that information, GDB can determine at translation time |
| whether a given expression will overflow the stack. But this spec |
| isn't about what kinds of error-checking GDB ought to do. |
| |
| Why are you doing everything in LONGEST? |
| Speed isn't important, but agent code size is; using LONGEST |
| brings in a bunch of support code to do things like division, etc. |
| So this is a serious concern. |
| |
| First, note that you don't need different bytecodes for different |
| operand sizes. You can generate code without _knowing_ how big the |
| stack elements actually are on the target. If the target only |
| supports 32-bit ints, and you don't send any 64-bit bytecodes, |
| everything just works. The observation here is that the MIPS and |
| the Alpha have only fixed-size registers, and you can still get |
| C's semantics even though most instructions only operate on |
| full-sized words. You just need to make sure everything is |
| properly sign-extended at the right times. So there is no need |
| for 32- and 64-bit variants of the bytecodes. Just implement |
| everything using the largest size you support. |
| |
| GDB should certainly check to see what sizes the target supports, |
| so the user can get an error earlier, rather than later. But this |
| information is not necessary for correctness. |
| |
| Why don't you have `>' or `<=' operators? |
| I want to keep the interpreter small, and we don't need them. We |
| can combine the `less_' opcodes with `log_not', and swap the order |
| of the operands, yielding all four asymmetrical comparison |
| operators. For example, `(x <= y)' is `! (x > y)', which is `! (y |
| < x)'. |
| |
| Why do you have `log_not'? |
| Why do you have `ext'? |
| Why do you have `zero_ext'? |
| These are all easily synthesized from other instructions, but I |
| expect them to be used frequently, and they're simple, so I |
| include them to keep bytecode strings short. |
| |
| `log_not' is equivalent to `const8 0 equal'; it's used in half the |
| relational operators. |
| |
| `ext N' is equivalent to `const8 S-N lsh const8 S-N rsh_signed', |
| where S is the size of the stack elements; it follows `refM' and |
| REG bytecodes when the value should be signed. See the next |
| bulleted item. |
| |
| `zero_ext N' is equivalent to `constM MASK log_and'; it's used |
| whenever we push the value of a register, because we can't assume |
| the upper bits of the register aren't garbage. |
| |
| Why not have sign-extending variants of the `ref' operators? |
| Because that would double the number of `ref' operators, and we |
| need the `ext' bytecode anyway for accessing bitfields. |
| |
| Why not have constant-address variants of the `ref' operators? |
| Because that would double the number of `ref' operators again, and |
| `const32 ADDRESS ref32' is only one byte longer. |
| |
| Why do the `refN' operators have to support unaligned fetches? |
| GDB will generate bytecode that fetches multi-byte values at |
| unaligned addresses whenever the executable's debugging |
| information tells it to. Furthermore, GDB does not know the value |
| the pointer will have when GDB generates the bytecode, so it |
| cannot determine whether a particular fetch will be aligned or not. |
| |
| In particular, structure bitfields may be several bytes long, but |
| follow no alignment rules; members of packed structures are not |
| necessarily aligned either. |
| |
| In general, there are many cases where unaligned references occur |
| in correct C code, either at the programmer's explicit request, or |
| at the compiler's discretion. Thus, it is simpler to make the GDB |
| agent bytecodes work correctly in all circumstances than to make |
| GDB guess in each case whether the compiler did the usual thing. |
| |
| Why are there no side-effecting operators? |
| Because our current client doesn't want them? That's a cheap |
| answer. I think the real answer is that I'm afraid of |
| implementing function calls. We should re-visit this issue after |
| the present contract is delivered. |
| |
| Why aren't the `goto' ops PC-relative? |
| The interpreter has the base address around anyway for PC bounds |
| checking, and it seemed simpler. |
| |
| Why is there only one offset size for the `goto' ops? |
| Offsets are currently sixteen bits. I'm not happy with this |
| situation either: |
| |
| Suppose we have multiple branch ops with different offset sizes. |
| As I generate code left-to-right, all my jumps are forward jumps |
| (there are no loops in expressions), so I never know the target |
| when I emit the jump opcode. Thus, I have to either always assume |
| the largest offset size, or do jump relaxation on the code after I |
| generate it, which seems like a big waste of time. |
| |
| I can imagine a reasonable expression being longer than 256 bytes. |
| I can't imagine one being longer than 64k. Thus, we need 16-bit |
| offsets. This kind of reasoning is so bogus, but relaxation is |
| pathetic. |
| |
| The other approach would be to generate code right-to-left. Then |
| I'd always know my offset size. That might be fun. |
| |
| Where is the function call bytecode? |
| When we add side-effects, we should add this. |
| |
| Why does the `reg' bytecode take a 16-bit register number? |
| Intel's IA-64 architecture has 128 general-purpose registers, and |
| 128 floating-point registers, and I'm sure it has some random |
| control registers. |
| |
| Why do we need `trace' and `trace_quick'? |
| Because GDB needs to record all the memory contents and registers |
| an expression touches. If the user wants to evaluate an expression |
| `x->y->z', the agent must record the values of `x' and `x->y' as |
| well as the value of `x->y->z'. |
| |
| Don't the `trace' bytecodes make the interpreter less general? |
| They do mean that the interpreter contains special-purpose code, |
| but that doesn't mean the interpreter can only be used for that |
| purpose. If an expression doesn't use the `trace' bytecodes, they |
| don't get in its way. |
| |
| Why doesn't `trace_quick' consume its arguments the way everything else does? |
| In general, you do want your operators to consume their arguments; |
| it's consistent, and generally reduces the amount of stack |
| rearrangement necessary. However, `trace_quick' is a kludge to |
| save space; it only exists so we needn't write `dup const8 SIZE |
| trace' before every memory reference. Therefore, it's okay for it |
| not to consume its arguments; it's meant for a specific context in |
| which we know exactly what it should do with the stack. If we're |
| going to have a kludge, it should be an effective kludge. |
| |
| Why does `trace16' exist? |
| That opcode was added by the customer that contracted Cygnus for |
| the data tracing work. I personally think it is unnecessary; |
| objects that large will be quite rare, so it is okay to use `dup |
| const16 SIZE trace' in those cases. |
| |
| Whatever we decide to do with `trace16', we should at least leave |
| opcode 0x30 reserved, to remain compatible with the customer who |
| added it. |
| |
| |
| |
| File: gdb.info, Node: Trace File Format, Next: Copying, Prev: Operating System Information, Up: Top |
| |
| Appendix F Trace File Format |
| **************************** |
| |
| The trace file comes in three parts: a header, a textual description |
| section, and a trace frame section with binary data. |
| |
| The header has the form `\x7fTRACE0\n'. The first byte is `0x7f' so |
| as to indicate that the file contains binary data, while the `0' is a |
| version number that may have different values in the future. |
| |
| The description section consists of multiple lines of ASCII text |
| separated by newline characters (`0xa'). The lines may include a |
| variety of optional descriptive or context-setting information, such as |
| tracepoint definitions or register set size. GDB will ignore any line |
| that it does not recognize. An empty line marks the end of this |
| section. |
| |
| The trace frame section consists of a number of consecutive frames. |
| Each frame begins with a two-byte tracepoint number, followed by a |
| four-byte size giving the amount of data in the frame. The data in the |
| frame consists of a number of blocks, each introduced by a character |
| indicating its type (at least register, memory, and trace state |
| variable). The data in this section is raw binary, not a hexadecimal |
| or other encoding; its endianness matches the target's endianness. |
| |
| `R BYTES' |
| Register block. The number and ordering of bytes matches that of a |
| `g' packet in the remote protocol. Note that these are the actual |
| bytes, in target order and GDB register order, not a hexadecimal |
| encoding. |
| |
| `M ADDRESS LENGTH BYTES...' |
| Memory block. This is a contiguous block of memory, at the 8-byte |
| address ADDRESS, with a 2-byte length LENGTH, followed by LENGTH |
| bytes. |
| |
| `V NUMBER VALUE' |
| Trace state variable block. This records the 8-byte signed value |
| VALUE of trace state variable numbered NUMBER. |
| |
| |
| Future enhancements of the trace file format may include additional |
| types of blocks. |
| |
| |
| File: gdb.info, Node: Target Descriptions, Next: Operating System Information, Prev: Agent Expressions, Up: Top |
| |
| Appendix G Target Descriptions |
| ****************************** |
| |
| *Warning:* target descriptions are still under active development, and |
| the contents and format may change between GDB releases. The format is |
| expected to stabilize in the future. |
| |
| One of the challenges of using GDB to debug embedded systems is that |
| there are so many minor variants of each processor architecture in use. |
| It is common practice for vendors to start with a standard processor |
| core -- ARM, PowerPC, or MIPS, for example -- and then make changes to |
| adapt it to a particular market niche. Some architectures have |
| hundreds of variants, available from dozens of vendors. This leads to |
| a number of problems: |
| |
| * With so many different customized processors, it is difficult for |
| the GDB maintainers to keep up with the changes. |
| |
| * Since individual variants may have short lifetimes or limited |
| audiences, it may not be worthwhile to carry information about |
| every variant in the GDB source tree. |
| |
| * When GDB does support the architecture of the embedded system at |
| hand, the task of finding the correct architecture name to give the |
| `set architecture' command can be error-prone. |
| |
| To address these problems, the GDB remote protocol allows a target |
| system to not only identify itself to GDB, but to actually describe its |
| own features. This lets GDB support processor variants it has never |
| seen before -- to the extent that the descriptions are accurate, and |
| that GDB understands them. |
| |
| GDB must be linked with the Expat library to support XML target |
| descriptions. *Note Expat::. |
| |
| * Menu: |
| |
| * Retrieving Descriptions:: How descriptions are fetched from a target. |
| * Target Description Format:: The contents of a target description. |
| * Predefined Target Types:: Standard types available for target |
| descriptions. |
| * Standard Target Features:: Features GDB knows about. |
| |
| |
| File: gdb.info, Node: Retrieving Descriptions, Next: Target Description Format, Up: Target Descriptions |
| |
| G.1 Retrieving Descriptions |
| =========================== |
| |
| Target descriptions can be read from the target automatically, or |
| specified by the user manually. The default behavior is to read the |
| description from the target. GDB retrieves it via the remote protocol |
| using `qXfer' requests (*note qXfer: General Query Packets.). The |
| ANNEX in the `qXfer' packet will be `target.xml'. The contents of the |
| `target.xml' annex are an XML document, of the form described in *Note |
| Target Description Format::. |
| |
| Alternatively, you can specify a file to read for the target |
| description. If a file is set, the target will not be queried. The |
| commands to specify a file are: |
| |
| `set tdesc filename PATH' |
| Read the target description from PATH. |
| |
| `unset tdesc filename' |
| Do not read the XML target description from a file. GDB will use |
| the description supplied by the current target. |
| |
| `show tdesc filename' |
| Show the filename to read for a target description, if any. |
| |
| |
| File: gdb.info, Node: Target Description Format, Next: Predefined Target Types, Prev: Retrieving Descriptions, Up: Target Descriptions |
| |
| G.2 Target Description Format |
| ============================= |
| |
| A target description annex is an XML (http://www.w3.org/XML/) document |
| which complies with the Document Type Definition provided in the GDB |
| sources in `gdb/features/gdb-target.dtd'. This means you can use |
| generally available tools like `xmllint' to check that your feature |
| descriptions are well-formed and valid. However, to help people |
| unfamiliar with XML write descriptions for their targets, we also |
| describe the grammar here. |
| |
| Target descriptions can identify the architecture of the remote |
| target and (for some architectures) provide information about custom |
| register sets. They can also identify the OS ABI of the remote target. |
| GDB can use this information to autoconfigure for your target, or to |
| warn you if you connect to an unsupported target. |
| |
| Here is a simple target description: |
| |
| <target version="1.0"> |
| <architecture>i386:x86-64</architecture> |
| </target> |
| |
| This minimal description only says that the target uses the x86-64 |
| architecture. |
| |
| A target description has the following overall form, with [ ] marking |
| optional elements and ... marking repeatable elements. The elements |
| are explained further below. |
| |
| <?xml version="1.0"?> |
| <!DOCTYPE target SYSTEM "gdb-target.dtd"> |
| <target version="1.0"> |
| [ARCHITECTURE] |
| [OSABI] |
| [COMPATIBLE] |
| [FEATURE...] |
| </target> |
| |
| The description is generally insensitive to whitespace and line breaks, |
| under the usual common-sense rules. The XML version declaration and |
| document type declaration can generally be omitted (GDB does not |
| require them), but specifying them may be useful for XML validation |
| tools. The `version' attribute for `<target>' may also be omitted, but |
| we recommend including it; if future versions of GDB use an incompatible |
| revision of `gdb-target.dtd', they will detect and report the version |
| mismatch. |
| |
| G.2.1 Inclusion |
| --------------- |
| |
| It can sometimes be valuable to split a target description up into |
| several different annexes, either for organizational purposes, or to |
| share files between different possible target descriptions. You can |
| divide a description into multiple files by replacing any element of |
| the target description with an inclusion directive of the form: |
| |
| <xi:include href="DOCUMENT"/> |
| |
| When GDB encounters an element of this form, it will retrieve the named |
| XML DOCUMENT, and replace the inclusion directive with the contents of |
| that document. If the current description was read using `qXfer', then |
| so will be the included document; DOCUMENT will be interpreted as the |
| name of an annex. If the current description was read from a file, GDB |
| will look for DOCUMENT as a file in the same directory where it found |
| the original description. |
| |
| G.2.2 Architecture |
| ------------------ |
| |
| An `<architecture>' element has this form: |
| |
| <architecture>ARCH</architecture> |
| |
| ARCH is one of the architectures from the set accepted by `set |
| architecture' (*note Specifying a Debugging Target: Targets.). |
| |
| G.2.3 OS ABI |
| ------------ |
| |
| This optional field was introduced in GDB version 7.0. Previous |
| versions of GDB ignore it. |
| |
| An `<osabi>' element has this form: |
| |
| <osabi>ABI-NAME</osabi> |
| |
| ABI-NAME is an OS ABI name from the same selection accepted by |
| `set osabi' (*note Configuring the Current ABI: ABI.). |
| |
| G.2.4 Compatible Architecture |
| ----------------------------- |
| |
| This optional field was introduced in GDB version 7.0. Previous |
| versions of GDB ignore it. |
| |
| A `<compatible>' element has this form: |
| |
| <compatible>ARCH</compatible> |
| |
| ARCH is one of the architectures from the set accepted by `set |
| architecture' (*note Specifying a Debugging Target: Targets.). |
| |
| A `<compatible>' element is used to specify that the target is able |
| to run binaries in some other than the main target architecture given |
| by the `<architecture>' element. For example, on the Cell Broadband |
| Engine, the main architecture is `powerpc:common' or |
| `powerpc:common64', but the system is able to run binaries in the `spu' |
| architecture as well. The way to describe this capability with |
| `<compatible>' is as follows: |
| |
| <architecture>powerpc:common</architecture> |
| <compatible>spu</compatible> |
| |
| G.2.5 Features |
| -------------- |
| |
| Each `<feature>' describes some logical portion of the target system. |
| Features are currently used to describe available CPU registers and the |
| types of their contents. A `<feature>' element has this form: |
| |
| <feature name="NAME"> |
| [TYPE...] |
| REG... |
| </feature> |
| |
| Each feature's name should be unique within the description. The name |
| of a feature does not matter unless GDB has some special knowledge of |
| the contents of that feature; if it does, the feature should have its |
| standard name. *Note Standard Target Features::. |
| |
| G.2.6 Types |
| ----------- |
| |
| Any register's value is a collection of bits which GDB must interpret. |
| The default interpretation is a two's complement integer, but other |
| types can be requested by name in the register description. Some |
| predefined types are provided by GDB (*note Predefined Target Types::), |
| and the description can define additional composite types. |
| |
| Each type element must have an `id' attribute, which gives a unique |
| (within the containing `<feature>') name to the type. Types must be |
| defined before they are used. |
| |
| Some targets offer vector registers, which can be treated as arrays |
| of scalar elements. These types are written as `<vector>' elements, |
| specifying the array element type, TYPE, and the number of elements, |
| COUNT: |
| |
| <vector id="ID" type="TYPE" count="COUNT"/> |
| |
| If a register's value is usefully viewed in multiple ways, define it |
| with a union type containing the useful representations. The `<union>' |
| element contains one or more `<field>' elements, each of which has a |
| NAME and a TYPE: |
| |
| <union id="ID"> |
| <field name="NAME" type="TYPE"/> |
| ... |
| </union> |
| |
| If a register's value is composed from several separate values, |
| define it with a structure type. There are two forms of the `<struct>' |
| element; a `<struct>' element must either contain only bitfields or |
| contain no bitfields. If the structure contains only bitfields, its |
| total size in bytes must be specified, each bitfield must have an |
| explicit start and end, and bitfields are automatically assigned an |
| integer type. The field's START should be less than or equal to its |
| END, and zero represents the least significant bit. |
| |
| <struct id="ID" size="SIZE"> |
| <field name="NAME" start="START" end="END"/> |
| ... |
| </struct> |
| |
| If the structure contains no bitfields, then each field has an |
| explicit type, and no implicit padding is added. |
| |
| <struct id="ID"> |
| <field name="NAME" type="TYPE"/> |
| ... |
| </struct> |
| |
| If a register's value is a series of single-bit flags, define it with |
| a flags type. The `<flags>' element has an explicit SIZE and contains |
| one or more `<field>' elements. Each field has a NAME, a START, and an |
| END. Only single-bit flags are supported. |
| |
| <flags id="ID" size="SIZE"> |
| <field name="NAME" start="START" end="END"/> |
| ... |
| </flags> |
| |
| G.2.7 Registers |
| --------------- |
| |
| Each register is represented as an element with this form: |
| |
| <reg name="NAME" |
| bitsize="SIZE" |
| [regnum="NUM"] |
| [save-restore="SAVE-RESTORE"] |
| [type="TYPE"] |
| [group="GROUP"]/> |
| |
| The components are as follows: |
| |
| NAME |
| The register's name; it must be unique within the target |
| description. |
| |
| BITSIZE |
| The register's size, in bits. |
| |
| REGNUM |
| The register's number. If omitted, a register's number is one |
| greater than that of the previous register (either in the current |
| feature or in a preceeding feature); the first register in the |
| target description defaults to zero. This register number is used |
| to read or write the register; e.g. it is used in the remote `p' |
| and `P' packets, and registers appear in the `g' and `G' packets |
| in order of increasing register number. |
| |
| SAVE-RESTORE |
| Whether the register should be preserved across inferior function |
| calls; this must be either `yes' or `no'. The default is `yes', |
| which is appropriate for most registers except for some system |
| control registers; this is not related to the target's ABI. |
| |
| TYPE |
| The type of the register. TYPE may be a predefined type, a type |
| defined in the current feature, or one of the special types `int' |
| and `float'. `int' is an integer type of the correct size for |
| BITSIZE, and `float' is a floating point type (in the |
| architecture's normal floating point format) of the correct size |
| for BITSIZE. The default is `int'. |
| |
| GROUP |
| The register group to which this register belongs. GROUP must be |
| either `general', `float', or `vector'. If no GROUP is specified, |
| GDB will not display the register in `info registers'. |
| |
| |
| |
| File: gdb.info, Node: Predefined Target Types, Next: Standard Target Features, Prev: Target Description Format, Up: Target Descriptions |
| |
| G.3 Predefined Target Types |
| =========================== |
| |
| Type definitions in the self-description can build up composite types |
| from basic building blocks, but can not define fundamental types. |
| Instead, standard identifiers are provided by GDB for the fundamental |
| types. The currently supported types are: |
| |
| `int8' |
| `int16' |
| `int32' |
| `int64' |
| `int128' |
| Signed integer types holding the specified number of bits. |
| |
| `uint8' |
| `uint16' |
| `uint32' |
| `uint64' |
| `uint128' |
| Unsigned integer types holding the specified number of bits. |
| |
| `code_ptr' |
| `data_ptr' |
| Pointers to unspecified code and data. The program counter and |
| any dedicated return address register may be marked as code |
| pointers; printing a code pointer converts it into a symbolic |
| address. The stack pointer and any dedicated address registers |
| may be marked as data pointers. |
| |
| `ieee_single' |
| Single precision IEEE floating point. |
| |
| `ieee_double' |
| Double precision IEEE floating point. |
| |
| `arm_fpa_ext' |
| The 12-byte extended precision format used by ARM FPA registers. |
| |
| `i387_ext' |
| The 10-byte extended precision format used by x87 registers. |
| |
| `i386_eflags' |
| 32bit EFLAGS register used by x86. |
| |
| `i386_mxcsr' |
| 32bit MXCSR register used by x86. |
| |
| |
| |
| File: gdb.info, Node: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions |
| |
| G.4 Standard Target Features |
| ============================ |
| |
| A target description must contain either no registers or all the |
| target's registers. If the description contains no registers, then GDB |
| will assume a default register layout, selected based on the |
| architecture. If the description contains any registers, the default |
| layout will not be used; the standard registers must be described in |
| the target description, in such a way that GDB can recognize them. |
| |
| This is accomplished by giving specific names to feature elements |
| which contain standard registers. GDB will look for features with |
| those names and verify that they contain the expected registers; if any |
| known feature is missing required registers, or if any required feature |
| is missing, GDB will reject the target description. You can add |
| additional registers to any of the standard features -- GDB will |
| display them just as if they were added to an unrecognized feature. |
| |
| This section lists the known features and their expected contents. |
| Sample XML documents for these features are included in the GDB source |
| tree, in the directory `gdb/features'. |
| |
| Names recognized by GDB should include the name of the company or |
| organization which selected the name, and the overall architecture to |
| which the feature applies; so e.g. the feature containing ARM core |
| registers is named `org.gnu.gdb.arm.core'. |
| |
| The names of registers are not case sensitive for the purpose of |
| recognizing standard features, but GDB will only display registers |
| using the capitalization used in the description. |
| |
| * Menu: |
| |
| * ARM Features:: |
| * i386 Features:: |
| * MIPS Features:: |
| * M68K Features:: |
| * PowerPC Features:: |
| |
| |
| File: gdb.info, Node: ARM Features, Next: i386 Features, Up: Standard Target Features |
| |
| G.4.1 ARM Features |
| ------------------ |
| |
| The `org.gnu.gdb.arm.core' feature is required for ARM targets. It |
| should contain registers `r0' through `r13', `sp', `lr', `pc', and |
| `cpsr'. |
| |
| The `org.gnu.gdb.arm.fpa' feature is optional. If present, it |
| should contain registers `f0' through `f7' and `fps'. |
| |
| The `org.gnu.gdb.xscale.iwmmxt' feature is optional. If present, it |
| should contain at least registers `wR0' through `wR15' and `wCGR0' |
| through `wCGR3'. The `wCID', `wCon', `wCSSF', and `wCASF' registers |
| are optional. |
| |
| The `org.gnu.gdb.arm.vfp' feature is optional. If present, it |
| should contain at least registers `d0' through `d15'. If they are |
| present, `d16' through `d31' should also be included. GDB will |
| synthesize the single-precision registers from halves of the |
| double-precision registers. |
| |
| The `org.gnu.gdb.arm.neon' feature is optional. It does not need to |
| contain registers; it instructs GDB to display the VFP double-precision |
| registers as vectors and to synthesize the quad-precision registers |
| from pairs of double-precision registers. If this feature is present, |
| `org.gnu.gdb.arm.vfp' must also be present and include 32 |
| double-precision registers. |
| |
| |
| File: gdb.info, Node: i386 Features, Next: MIPS Features, Prev: ARM Features, Up: Standard Target Features |
| |
| G.4.2 i386 Features |
| ------------------- |
| |
| The `org.gnu.gdb.i386.core' feature is required for i386/amd64 targets. |
| It should describe the following registers: |
| |
| - `eax' through `edi' plus `eip' for i386 |
| |
| - `rax' through `r15' plus `rip' for amd64 |
| |
| - `eflags', `cs', `ss', `ds', `es', `fs', `gs' |
| |
| - `st0' through `st7' |
| |
| - `fctrl', `fstat', `ftag', `fiseg', `fioff', `foseg', `fooff' and |
| `fop' |
| |
| The register sets may be different, depending on the target. |
| |
| The `org.gnu.gdb.i386.sse' feature is optional. It should describe |
| registers: |
| |
| - `xmm0' through `xmm7' for i386 |
| |
| - `xmm0' through `xmm15' for amd64 |
| |
| - `mxcsr' |
| |
| The `org.gnu.gdb.i386.avx' feature is optional and requires the |
| `org.gnu.gdb.i386.sse' feature. It should describe the upper 128 bits |
| of YMM registers: |
| |
| - `ymm0h' through `ymm7h' for i386 |
| |
| - `ymm0h' through `ymm15h' for amd64 |
| |
| - |
| The `org.gnu.gdb.i386.linux' feature is optional. It should |
| describe a single register, `orig_eax'. |
| |
| |
| File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: i386 Features, Up: Standard Target Features |
| |
| G.4.3 MIPS Features |
| ------------------- |
| |
| The `org.gnu.gdb.mips.cpu' feature is required for MIPS targets. It |
| should contain registers `r0' through `r31', `lo', `hi', and `pc'. |
| They may be 32-bit or 64-bit depending on the target. |
| |
| The `org.gnu.gdb.mips.cp0' feature is also required. It should |
| contain at least the `status', `badvaddr', and `cause' registers. They |
| may be 32-bit or 64-bit depending on the target. |
| |
| The `org.gnu.gdb.mips.fpu' feature is currently required, though it |
| may be optional in a future version of GDB. It should contain |
| registers `f0' through `f31', `fcsr', and `fir'. They may be 32-bit or |
| 64-bit depending on the target. |
| |
| The `org.gnu.gdb.mips.linux' feature is optional. It should contain |
| a single register, `restart', which is used by the Linux kernel to |
| control restartable syscalls. |
| |
| |
| File: gdb.info, Node: M68K Features, Next: PowerPC Features, Prev: MIPS Features, Up: Standard Target Features |
| |
| G.4.4 M68K Features |
| ------------------- |
| |
| ``org.gnu.gdb.m68k.core'' |
| ``org.gnu.gdb.coldfire.core'' |
| ``org.gnu.gdb.fido.core'' |
| One of those features must be always present. The feature that is |
| present determines which flavor of m68k is used. The feature that |
| is present should contain registers `d0' through `d7', `a0' |
| through `a5', `fp', `sp', `ps' and `pc'. |
| |
| ``org.gnu.gdb.coldfire.fp'' |
| This feature is optional. If present, it should contain registers |
| `fp0' through `fp7', `fpcontrol', `fpstatus' and `fpiaddr'. |
| |
| |
| File: gdb.info, Node: PowerPC Features, Prev: M68K Features, Up: Standard Target Features |
| |
| G.4.5 PowerPC Features |
| ---------------------- |
| |
| The `org.gnu.gdb.power.core' feature is required for PowerPC targets. |
| It should contain registers `r0' through `r31', `pc', `msr', `cr', |
| `lr', `ctr', and `xer'. They may be 32-bit or 64-bit depending on the |
| target. |
| |
| The `org.gnu.gdb.power.fpu' feature is optional. It should contain |
| registers `f0' through `f31' and `fpscr'. |
| |
| The `org.gnu.gdb.power.altivec' feature is optional. It should |
| contain registers `vr0' through `vr31', `vscr', and `vrsave'. |
| |
| The `org.gnu.gdb.power.vsx' feature is optional. It should contain |
| registers `vs0h' through `vs31h'. GDB will combine these registers |
| with the floating point registers (`f0' through `f31') and the altivec |
| registers (`vr0' through `vr31') to present the 128-bit wide registers |
| `vs0' through `vs63', the set of vector registers for POWER7. |
| |
| The `org.gnu.gdb.power.spe' feature is optional. It should contain |
| registers `ev0h' through `ev31h', `acc', and `spefscr'. SPE targets |
| should provide 32-bit registers in `org.gnu.gdb.power.core' and provide |
| the upper halves in `ev0h' through `ev31h'. GDB will combine these to |
| present registers `ev0' through `ev31' to the user. |
| |
| |
| File: gdb.info, Node: Operating System Information, Next: Trace File Format, Prev: Target Descriptions, Up: Top |
| |
| Appendix H Operating System Information |
| *************************************** |
| |
| * Menu: |
| |
| * Process list:: |
| |
| Users of GDB often wish to obtain information about the state of the |
| operating system running on the target--for example the list of |
| processes, or the list of open files. This section describes the |
| mechanism that makes it possible. This mechanism is similar to the |
| target features mechanism (*note Target Descriptions::), but focuses on |
| a different aspect of target. |
| |
| Operating system information is retrived from the target via the |
| remote protocol, using `qXfer' requests (*note qXfer osdata read::). |
| The object name in the request should be `osdata', and the ANNEX |
| identifies the data to be fetched. |
| |
| |
| File: gdb.info, Node: Process list, Up: Operating System Information |
| |
| H.1 Process list |
| ================ |
| |
| When requesting the process list, the ANNEX field in the `qXfer' |
| request should be `processes'. The returned data is an XML document. |
| The formal syntax of this document is defined in |
| `gdb/features/osdata.dtd'. |
| |
| An example document is: |
| |
| <?xml version="1.0"?> |
| <!DOCTYPE target SYSTEM "osdata.dtd"> |
| <osdata type="processes"> |
| <item> |
| <column name="pid">1</column> |
| <column name="user">root</column> |
| <column name="command">/sbin/init</column> |
| <column name="cores">1,2,3</column> |
| </item> |
| </osdata> |
| |
| Each item should include a column whose name is `pid'. The value of |
| that column should identify the process on the target. The `user' and |
| `command' columns are optional, and will be displayed by GDB. The |
| `cores' column, if present, should contain a comma-separated list of |
| cores that this process is running on. Target may provide additional |
| columns, which GDB currently ignores. |
| |
| |
| File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Trace File Format, Up: Top |
| |
| Appendix I GNU GENERAL PUBLIC LICENSE |
| ************************************* |
| |
| Version 3, 29 June 2007 |
| |
| Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/' |
| |
| Everyone is permitted to copy and distribute verbatim copies of this |
| license document, but changing it is not allowed. |
| |
| Preamble |
| ======== |
| |
| The GNU General Public License is a free, copyleft license for software |
| and other kinds of works. |
| |
| The licenses for most software and other practical works are designed |
| to take away your freedom to share and change the works. By contrast, |
| the GNU General Public License is intended to guarantee your freedom to |
| share and change all versions of a program--to make sure it remains |
| free software for all its users. We, the Free Software Foundation, use |
| the GNU General Public License for most of our software; it applies |
| also to any other work released this way by its authors. You can apply |
| it to your programs, too. |
| |
| When we speak of free software, we are referring to freedom, not |
| price. Our General Public Licenses are designed to make sure that you |
| have the freedom to distribute copies of free software (and charge for |
| them if you wish), that you receive source code or can get it if you |
| want it, that you can change the software or use pieces of it in new |
| free programs, and that you know you can do these things. |
| |
| To protect your rights, we need to prevent others from denying you |
| these rights or asking you to surrender the rights. Therefore, you |
| have certain responsibilities if you distribute copies of the software, |
| or if you modify it: responsibilities to respect the freedom of others. |
| |
| For example, if you distribute copies of such a program, whether |
| gratis or for a fee, you must pass on to the recipients the same |
| freedoms that you received. You must make sure that they, too, receive |
| or can get the source code. And you must show them these terms so they |
| know their rights. |
| |
| Developers that use the GNU GPL protect your rights with two steps: |
| (1) assert copyright on the software, and (2) offer you this License |
| giving you legal permission to copy, distribute and/or modify it. |
| |
| For the developers' and authors' protection, the GPL clearly explains |
| that there is no warranty for this free software. For both users' and |
| authors' sake, the GPL requires that modified versions be marked as |
| changed, so that their problems will not be attributed erroneously to |
| authors of previous versions. |
| |
| Some devices are designed to deny users access to install or run |
| modified versions of the software inside them, although the |
| manufacturer can do so. This is fundamentally incompatible with the |
| aim of protecting users' freedom to change the software. The |
| systematic pattern of such abuse occurs in the area of products for |
| individuals to use, which is precisely where it is most unacceptable. |
| Therefore, we have designed this version of the GPL to prohibit the |
| practice for those products. If such problems arise substantially in |
| other domains, we stand ready to extend this provision to those domains |
| in future versions of the GPL, as needed to protect the freedom of |
| users. |
| |
| Finally, every program is threatened constantly by software patents. |
| States should not allow patents to restrict development and use of |
| software on general-purpose computers, but in those that do, we wish to |
| avoid the special danger that patents applied to a free program could |
| make it effectively proprietary. To prevent this, the GPL assures that |
| patents cannot be used to render the program non-free. |
| |
| The precise terms and conditions for copying, distribution and |
| modification follow. |
| |
| TERMS AND CONDITIONS |
| ==================== |
| |
| 0. Definitions. |
| |
| "This License" refers to version 3 of the GNU General Public |
| License. |
| |
| "Copyright" also means copyright-like laws that apply to other |
| kinds of works, such as semiconductor masks. |
| |
| "The Program" refers to any copyrightable work licensed under this |
| License. Each licensee is addressed as "you". "Licensees" and |
| "recipients" may be individuals or organizations. |
| |
| To "modify" a work means to copy from or adapt all or part of the |
| work in a fashion requiring copyright permission, other than the |
| making of an exact copy. The resulting work is called a "modified |
| version" of the earlier work or a work "based on" the earlier work. |
| |
| A "covered work" means either the unmodified Program or a work |
| based on the Program. |
| |
| To "propagate" a work means to do anything with it that, without |
| permission, would make you directly or secondarily liable for |
| infringement under applicable copyright law, except executing it |
| on a computer or modifying a private copy. Propagation includes |
| copying, distribution (with or without modification), making |
| available to the public, and in some countries other activities as |
| well. |
| |
| To "convey" a work means any kind of propagation that enables other |
| parties to make or receive copies. Mere interaction with a user |
| through a computer network, with no transfer of a copy, is not |
| conveying. |
| |
| An interactive user interface displays "Appropriate Legal Notices" |
| to the extent that it includes a convenient and prominently visible |
| feature that (1) displays an appropriate copyright notice, and (2) |
| tells the user that there is no warranty for the work (except to |
| the extent that warranties are provided), that licensees may |
| convey the work under this License, and how to view a copy of this |
| License. If the interface presents a list of user commands or |
| options, such as a menu, a prominent item in the list meets this |
| criterion. |
| |
| 1. Source Code. |
| |
| The "source code" for a work means the preferred form of the work |
| for making modifications to it. "Object code" means any |
| non-source form of a work. |
| |
| A "Standard Interface" means an interface that either is an |
| official standard defined by a recognized standards body, or, in |
| the case of interfaces specified for a particular programming |
| language, one that is widely used among developers working in that |
| language. |
| |
| The "System Libraries" of an executable work include anything, |
| other than the work as a whole, that (a) is included in the normal |
| form of packaging a Major Component, but which is not part of that |
| Major Component, and (b) serves only to enable use of the work |
| with that Major Component, or to implement a Standard Interface |
| for which an implementation is available to the public in source |
| code form. A "Major Component", in this context, means a major |
| essential component (kernel, window system, and so on) of the |
| specific operating system (if any) on which the executable work |
| runs, or a compiler used to produce the work, or an object code |
| interpreter used to run it. |
| |
| The "Corresponding Source" for a work in object code form means all |
| the source code needed to generate, install, and (for an executable |
| work) run the object code and to modify the work, including |
| scripts to control those activities. However, it does not include |
| the work's System Libraries, or general-purpose tools or generally |
| available free programs which are used unmodified in performing |
| those activities but which are not part of the work. For example, |
| Corresponding Source includes interface definition files |
| associated with source files for the work, and the source code for |
| shared libraries and dynamically linked subprograms that the work |
| is specifically designed to require, such as by intimate data |
| communication or control flow between those subprograms and other |
| parts of the work. |
| |
| The Corresponding Source need not include anything that users can |
| regenerate automatically from other parts of the Corresponding |
| Source. |
| |
| The Corresponding Source for a work in source code form is that |
| same work. |
| |
| 2. Basic Permissions. |
| |
| All rights granted under this License are granted for the term of |
| copyright on the Program, and are irrevocable provided the stated |
| conditions are met. This License explicitly affirms your unlimited |
| permission to run the unmodified Program. The output from running |
| a covered work is covered by this License only if the output, |
| given its content, constitutes a covered work. This License |
| acknowledges your rights of fair use or other equivalent, as |
| provided by copyright law. |
| |
| You may make, run and propagate covered works that you do not |
| convey, without conditions so long as your license otherwise |
| remains in force. You may convey covered works to others for the |
| sole purpose of having them make modifications exclusively for |
| you, or provide you with facilities for running those works, |
| provided that you comply with the terms of this License in |
| conveying all material for which you do not control copyright. |
| Those thus making or running the covered works for you must do so |
| exclusively on your behalf, under your direction and control, on |
| terms that prohibit them from making any copies of your |
| copyrighted material outside their relationship with you. |
| |
| Conveying under any other circumstances is permitted solely under |
| the conditions stated below. Sublicensing is not allowed; section |
| 10 makes it unnecessary. |
| |
| 3. Protecting Users' Legal Rights From Anti-Circumvention Law. |
| |
| No covered work shall be deemed part of an effective technological |
| measure under any applicable law fulfilling obligations under |
| article 11 of the WIPO copyright treaty adopted on 20 December |
| 1996, or similar laws prohibiting or restricting circumvention of |
| such measures. |
| |
| When you convey a covered work, you waive any legal power to forbid |
| circumvention of technological measures to the extent such |
| circumvention is effected by exercising rights under this License |
| with respect to the covered work, and you disclaim any intention |
| to limit operation or modification of the work as a means of |
| enforcing, against the work's users, your or third parties' legal |
| rights to forbid circumvention of technological measures. |
| |
| 4. Conveying Verbatim Copies. |
| |
| You may convey verbatim copies of the Program's source code as you |
| receive it, in any medium, provided that you conspicuously and |
| appropriately publish on each copy an appropriate copyright notice; |
| keep intact all notices stating that this License and any |
| non-permissive terms added in accord with section 7 apply to the |
| code; keep intact all notices of the absence of any warranty; and |
| give all recipients a copy of this License along with the Program. |
| |
| You may charge any price or no price for each copy that you convey, |
| and you may offer support or warranty protection for a fee. |
| |
| 5. Conveying Modified Source Versions. |
| |
| You may convey a work based on the Program, or the modifications to |
| produce it from the Program, in the form of source code under the |
| terms of section 4, provided that you also meet all of these |
| conditions: |
| |
| a. The work must carry prominent notices stating that you |
| modified it, and giving a relevant date. |
| |
| b. The work must carry prominent notices stating that it is |
| released under this License and any conditions added under |
| section 7. This requirement modifies the requirement in |
| section 4 to "keep intact all notices". |
| |
| c. You must license the entire work, as a whole, under this |
| License to anyone who comes into possession of a copy. This |
| License will therefore apply, along with any applicable |
| section 7 additional terms, to the whole of the work, and all |
| its parts, regardless of how they are packaged. This License |
| gives no permission to license the work in any other way, but |
| it does not invalidate such permission if you have separately |
| received it. |
| |
| d. If the work has interactive user interfaces, each must display |
| Appropriate Legal Notices; however, if the Program has |
| interactive interfaces that do not display Appropriate Legal |
| Notices, your work need not make them do so. |
| |
| A compilation of a covered work with other separate and independent |
| works, which are not by their nature extensions of the covered |
| work, and which are not combined with it such as to form a larger |
| program, in or on a volume of a storage or distribution medium, is |
| called an "aggregate" if the compilation and its resulting |
| copyright are not used to limit the access or legal rights of the |
| compilation's users beyond what the individual works permit. |
| Inclusion of a covered work in an aggregate does not cause this |
| License to apply to the other parts of the aggregate. |
| |
| 6. Conveying Non-Source Forms. |
| |
| You may convey a covered work in object code form under the terms |
| of sections 4 and 5, provided that you also convey the |
| machine-readable Corresponding Source under the terms of this |
| License, in one of these ways: |
| |
| a. Convey the object code in, or embodied in, a physical product |
| (including a physical distribution medium), accompanied by the |
| Corresponding Source fixed on a durable physical medium |
| customarily used for software interchange. |
| |
| b. Convey the object code in, or embodied in, a physical product |
| (including a physical distribution medium), accompanied by a |
| written offer, valid for at least three years and valid for |
| as long as you offer spare parts or customer support for that |
| product model, to give anyone who possesses the object code |
| either (1) a copy of the Corresponding Source for all the |
| software in the product that is covered by this License, on a |
| durable physical medium customarily used for software |
| interchange, for a price no more than your reasonable cost of |
| physically performing this conveying of source, or (2) access |
| to copy the Corresponding Source from a network server at no |
| charge. |
| |
| c. Convey individual copies of the object code with a copy of |
| the written offer to provide the Corresponding Source. This |
| alternative is allowed only occasionally and noncommercially, |
| and only if you received the object code with such an offer, |
| in accord with subsection 6b. |
| |
| d. Convey the object code by offering access from a designated |
| place (gratis or for a charge), and offer equivalent access |
| to the Corresponding Source in the same way through the same |
| place at no further charge. You need not require recipients |
| to copy the Corresponding Source along with the object code. |
| If the place to copy the object code is a network server, the |
| Corresponding Source may be on a different server (operated |
| by you or a third party) that supports equivalent copying |
| facilities, provided you maintain clear directions next to |
| the object code saying where to find the Corresponding Source. |
| Regardless of what server hosts the Corresponding Source, you |
| remain obligated to ensure that it is available for as long |
| as needed to satisfy these requirements. |
| |
| e. Convey the object code using peer-to-peer transmission, |
| provided you inform other peers where the object code and |
| Corresponding Source of the work are being offered to the |
| general public at no charge under subsection 6d. |
| |
| |
| A separable portion of the object code, whose source code is |
| excluded from the Corresponding Source as a System Library, need |
| not be included in conveying the object code work. |
| |
| A "User Product" is either (1) a "consumer product", which means |
| any tangible personal property which is normally used for personal, |
| family, or household purposes, or (2) anything designed or sold for |
| incorporation into a dwelling. In determining whether a product |
| is a consumer product, doubtful cases shall be resolved in favor of |
| coverage. For a particular product received by a particular user, |
| "normally used" refers to a typical or common use of that class of |
| product, regardless of the status of the particular user or of the |
| way in which the particular user actually uses, or expects or is |
| expected to use, the product. A product is a consumer product |
| regardless of whether the product has substantial commercial, |
| industrial or non-consumer uses, unless such uses represent the |
| only significant mode of use of the product. |
| |
| "Installation Information" for a User Product means any methods, |
| procedures, authorization keys, or other information required to |
| install and execute modified versions of a covered work in that |
| User Product from a modified version of its Corresponding Source. |
| The information must suffice to ensure that the continued |
| functioning of the modified object code is in no case prevented or |
| interfered with solely because modification has been made. |
| |
| If you convey an object code work under this section in, or with, |
| or specifically for use in, a User Product, and the conveying |
| occurs as part of a transaction in which the right of possession |
| and use of the User Product is transferred to the recipient in |
| perpetuity or for a fixed term (regardless of how the transaction |
| is characterized), the Corresponding Source conveyed under this |
| section must be accompanied by the Installation Information. But |
| this requirement does not apply if neither you nor any third party |
| retains the ability to install modified object code on the User |
| Product (for example, the work has been installed in ROM). |
| |
| The requirement to provide Installation Information does not |
| include a requirement to continue to provide support service, |
| warranty, or updates for a work that has been modified or |
| installed by the recipient, or for the User Product in which it |
| has been modified or installed. Access to a network may be denied |
| when the modification itself materially and adversely affects the |
| operation of the network or violates the rules and protocols for |
| communication across the network. |
| |
| Corresponding Source conveyed, and Installation Information |
| provided, in accord with this section must be in a format that is |
| publicly documented (and with an implementation available to the |
| public in source code form), and must require no special password |
| or key for unpacking, reading or copying. |
| |
| 7. Additional Terms. |
| |
| "Additional permissions" are terms that supplement the terms of |
| this License by making exceptions from one or more of its |
| conditions. Additional permissions that are applicable to the |
| entire Program shall be treated as though they were included in |
| this License, to the extent that they are valid under applicable |
| law. If additional permissions apply only to part of the Program, |
| that part may be used separately under those permissions, but the |
| entire Program remains governed by this License without regard to |
| the additional permissions. |
| |
| When you convey a copy of a covered work, you may at your option |
| remove any additional permissions from that copy, or from any part |
| of it. (Additional permissions may be written to require their own |
| removal in certain cases when you modify the work.) You may place |
| additional permissions on material, added by you to a covered work, |
| for which you have or can give appropriate copyright permission. |
| |
| Notwithstanding any other provision of this License, for material |
| you add to a covered work, you may (if authorized by the copyright |
| holders of that material) supplement the terms of this License |
| with terms: |
| |
| a. Disclaiming warranty or limiting liability differently from |
| the terms of sections 15 and 16 of this License; or |
| |
| b. Requiring preservation of specified reasonable legal notices |
| or author attributions in that material or in the Appropriate |
| Legal Notices displayed by works containing it; or |
| |
| c. Prohibiting misrepresentation of the origin of that material, |
| or requiring that modified versions of such material be |
| marked in reasonable ways as different from the original |
| version; or |
| |
| d. Limiting the use for publicity purposes of names of licensors |
| or authors of the material; or |
| |
| e. Declining to grant rights under trademark law for use of some |
| trade names, trademarks, or service marks; or |
| |
| f. Requiring indemnification of licensors and authors of that |
| material by anyone who conveys the material (or modified |
| versions of it) with contractual assumptions of liability to |
| the recipient, for any liability that these contractual |
| assumptions directly impose on those licensors and authors. |
| |
| All other non-permissive additional terms are considered "further |
| restrictions" within the meaning of section 10. If the Program as |
| you received it, or any part of it, contains a notice stating that |
| it is governed by this License along with a term that is a further |
| restriction, you may remove that term. If a license document |
| contains a further restriction but permits relicensing or |
| conveying under this License, you may add to a covered work |
| material governed by the terms of that license document, provided |
| that the further restriction does not survive such relicensing or |
| conveying. |
| |
| If you add terms to a covered work in accord with this section, you |
| must place, in the relevant source files, a statement of the |
| additional terms that apply to those files, or a notice indicating |
| where to find the applicable terms. |
| |
| Additional terms, permissive or non-permissive, may be stated in |
| the form of a separately written license, or stated as exceptions; |
| the above requirements apply either way. |
| |
| 8. Termination. |
| |
| You may not propagate or modify a covered work except as expressly |
| provided under this License. Any attempt otherwise to propagate or |
| modify it is void, and will automatically terminate your rights |
| under this License (including any patent licenses granted under |
| the third paragraph of section 11). |
| |
| However, if you cease all violation of this License, then your |
| license from a particular copyright holder is reinstated (a) |
| provisionally, unless and until the copyright holder explicitly |
| and finally terminates your license, and (b) permanently, if the |
| copyright holder fails to notify you of the violation by some |
| reasonable means prior to 60 days after the cessation. |
| |
| Moreover, your license from a particular copyright holder is |
| reinstated permanently if the copyright holder notifies you of the |
| violation by some reasonable means, this is the first time you have |
| received notice of violation of this License (for any work) from |
| that copyright holder, and you cure the violation prior to 30 days |
| after your receipt of the notice. |
| |
| Termination of your rights under this section does not terminate |
| the licenses of parties who have received copies or rights from |
| you under this License. If your rights have been terminated and |
| not permanently reinstated, you do not qualify to receive new |
| licenses for the same material under section 10. |
| |
| 9. Acceptance Not Required for Having Copies. |
| |
| You are not required to accept this License in order to receive or |
| run a copy of the Program. Ancillary propagation of a covered work |
| occurring solely as a consequence of using peer-to-peer |
| transmission to receive a copy likewise does not require |
| acceptance. However, nothing other than this License grants you |
| permission to propagate or modify any covered work. These actions |
| infringe copyright if you do not accept this License. Therefore, |
| by modifying or propagating a covered work, you indicate your |
| acceptance of this License to do so. |
| |
| 10. Automatic Licensing of Downstream Recipients. |
| |
| Each time you convey a covered work, the recipient automatically |
| receives a license from the original licensors, to run, modify and |
| propagate that work, subject to this License. You are not |
| responsible for enforcing compliance by third parties with this |
| License. |
| |
| An "entity transaction" is a transaction transferring control of an |
| organization, or substantially all assets of one, or subdividing an |
| organization, or merging organizations. If propagation of a |
| covered work results from an entity transaction, each party to that |
| transaction who receives a copy of the work also receives whatever |
| licenses to the work the party's predecessor in interest had or |
| could give under the previous paragraph, plus a right to |
| possession of the Corresponding Source of the work from the |
| predecessor in interest, if the predecessor has it or can get it |
| with reasonable efforts. |
| |
| You may not impose any further restrictions on the exercise of the |
| rights granted or affirmed under this License. For example, you |
| may not impose a license fee, royalty, or other charge for |
| exercise of rights granted under this License, and you may not |
| initiate litigation (including a cross-claim or counterclaim in a |
| lawsuit) alleging that any patent claim is infringed by making, |
| using, selling, offering for sale, or importing the Program or any |
| portion of it. |
| |
| 11. Patents. |
| |
| A "contributor" is a copyright holder who authorizes use under this |
| License of the Program or a work on which the Program is based. |
| The work thus licensed is called the contributor's "contributor |
| version". |
| |
| A contributor's "essential patent claims" are all patent claims |
| owned or controlled by the contributor, whether already acquired or |
| hereafter acquired, that would be infringed by some manner, |
| permitted by this License, of making, using, or selling its |
| contributor version, but do not include claims that would be |
| infringed only as a consequence of further modification of the |
| contributor version. For purposes of this definition, "control" |
| includes the right to grant patent sublicenses in a manner |
| consistent with the requirements of this License. |
| |
| Each contributor grants you a non-exclusive, worldwide, |
| royalty-free patent license under the contributor's essential |
| patent claims, to make, use, sell, offer for sale, import and |
| otherwise run, modify and propagate the contents of its |
| contributor version. |
| |
| In the following three paragraphs, a "patent license" is any |
| express agreement or commitment, however denominated, not to |
| enforce a patent (such as an express permission to practice a |
| patent or covenant not to sue for patent infringement). To |
| "grant" such a patent license to a party means to make such an |
| agreement or commitment not to enforce a patent against the party. |
| |
| If you convey a covered work, knowingly relying on a patent |
| license, and the Corresponding Source of the work is not available |
| for anyone to copy, free of charge and under the terms of this |
| License, through a publicly available network server or other |
| readily accessible means, then you must either (1) cause the |
| Corresponding Source to be so available, or (2) arrange to deprive |
| yourself of the benefit of the patent license for this particular |
| work, or (3) arrange, in a manner consistent with the requirements |
| of this License, to extend the patent license to downstream |
| recipients. "Knowingly relying" means you have actual knowledge |
| that, but for the patent license, your conveying the covered work |
| in a country, or your recipient's use of the covered work in a |
| country, would infringe one or more identifiable patents in that |
| country that you have reason to believe are valid. |
| |
| If, pursuant to or in connection with a single transaction or |
| arrangement, you convey, or propagate by procuring conveyance of, a |
| covered work, and grant a patent license to some of the parties |
| receiving the covered work authorizing them to use, propagate, |
| modify or convey a specific copy of the covered work, then the |
| patent license you grant is automatically extended to all |
| recipients of the covered work and works based on it. |
| |
| A patent license is "discriminatory" if it does not include within |
| the scope of its coverage, prohibits the exercise of, or is |
| conditioned on the non-exercise of one or more of the rights that |
| are specifically granted under this License. You may not convey a |
| covered work if you are a party to an arrangement with a third |
| party that is in the business of distributing software, under |
| which you make payment to the third party based on the extent of |
| your activity of conveying the work, and under which the third |
| party grants, to any of the parties who would receive the covered |
| work from you, a discriminatory patent license (a) in connection |
| with copies of the covered work conveyed by you (or copies made |
| from those copies), or (b) primarily for and in connection with |
| specific products or compilations that contain the covered work, |
| unless you entered into that arrangement, or that patent license |
| was granted, prior to 28 March 2007. |
| |
| Nothing in this License shall be construed as excluding or limiting |
| any implied license or other defenses to infringement that may |
| otherwise be available to you under applicable patent law. |
| |
| 12. No Surrender of Others' Freedom. |
| |
| If conditions are imposed on you (whether by court order, |
| agreement or otherwise) that contradict the conditions of this |
| License, they do not excuse you from the conditions of this |
| License. If you cannot convey a covered work so as to satisfy |
| simultaneously your obligations under this License and any other |
| pertinent obligations, then as a consequence you may not convey it |
| at all. For example, if you agree to terms that obligate you to |
| collect a royalty for further conveying from those to whom you |
| convey the Program, the only way you could satisfy both those |
| terms and this License would be to refrain entirely from conveying |
| the Program. |
| |
| 13. Use with the GNU Affero General Public License. |
| |
| Notwithstanding any other provision of this License, you have |
| permission to link or combine any covered work with a work licensed |
| under version 3 of the GNU Affero General Public License into a |
| single combined work, and to convey the resulting work. The terms |
| of this License will continue to apply to the part which is the |
| covered work, but the special requirements of the GNU Affero |
| General Public License, section 13, concerning interaction through |
| a network will apply to the combination as such. |
| |
| 14. Revised Versions of this License. |
| |
| The Free Software Foundation may publish revised and/or new |
| versions of the GNU General Public License from time to time. |
| Such new versions will be similar in spirit to the present |
| version, but may differ in detail to address new problems or |
| concerns. |
| |
| Each version is given a distinguishing version number. If the |
| Program specifies that a certain numbered version of the GNU |
| General Public License "or any later version" applies to it, you |
| have the option of following the terms and conditions either of |
| that numbered version or of any later version published by the |
| Free Software Foundation. If the Program does not specify a |
| version number of the GNU General Public License, you may choose |
| any version ever published by the Free Software Foundation. |
| |
| If the Program specifies that a proxy can decide which future |
| versions of the GNU General Public License can be used, that |
| proxy's public statement of acceptance of a version permanently |
| authorizes you to choose that version for the Program. |
| |
| Later license versions may give you additional or different |
| permissions. However, no additional obligations are imposed on any |
| author or copyright holder as a result of your choosing to follow a |
| later version. |
| |
| 15. Disclaimer of Warranty. |
| |
| THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY |
| APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE |
| COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" |
| WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, |
| INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF |
| MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE |
| RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. |
| SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL |
| NECESSARY SERVICING, REPAIR OR CORRECTION. |
| |
| 16. Limitation of Liability. |
| |
| IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN |
| WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES |
| AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU |
| FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR |
| CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE |
| THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA |
| BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD |
| PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER |
| PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF |
| THE POSSIBILITY OF SUCH DAMAGES. |
| |
| 17. Interpretation of Sections 15 and 16. |
| |
| If the disclaimer of warranty and limitation of liability provided |
| above cannot be given local legal effect according to their terms, |
| reviewing courts shall apply local law that most closely |
| approximates an absolute waiver of all civil liability in |
| connection with the Program, unless a warranty or assumption of |
| liability accompanies a copy of the Program in return for a fee. |
| |
| |
| END OF TERMS AND CONDITIONS |
| =========================== |
| |
| How to Apply These Terms to Your New Programs |
| ============================================= |
| |
| If you develop a new program, and you want it to be of the greatest |
| possible use to the public, the best way to achieve this is to make it |
| free software which everyone can redistribute and change under these |
| terms. |
| |
| To do so, attach the following notices to the program. It is safest |
| to attach them to the start of each source file to most effectively |
| state the exclusion of warranty; and each file should have at least the |
| "copyright" line and a pointer to where the full notice is found. |
| |
| ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. |
| Copyright (C) YEAR NAME OF AUTHOR |
| |
| This program is free software: you can redistribute it and/or modify |
| it under the terms of the GNU General Public License as published by |
| the Free Software Foundation, either version 3 of the License, or (at |
| your option) any later version. |
| |
| This program is distributed in the hope that it will be useful, but |
| WITHOUT ANY WARRANTY; without even the implied warranty of |
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| General Public License for more details. |
| |
| You should have received a copy of the GNU General Public License |
| along with this program. If not, see `http://www.gnu.org/licenses/'. |
| |
| Also add information on how to contact you by electronic and paper |
| mail. |
| |
| If the program does terminal interaction, make it output a short |
| notice like this when it starts in an interactive mode: |
| |
| PROGRAM Copyright (C) YEAR NAME OF AUTHOR |
| This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. |
| This is free software, and you are welcome to redistribute it |
| under certain conditions; type `show c' for details. |
| |
| The hypothetical commands `show w' and `show c' should show the |
| appropriate parts of the General Public License. Of course, your |
| program's commands might be different; for a GUI interface, you would |
| use an "about box". |
| |
| You should also get your employer (if you work as a programmer) or |
| school, if any, to sign a "copyright disclaimer" for the program, if |
| necessary. For more information on this, and how to apply and follow |
| the GNU GPL, see `http://www.gnu.org/licenses/'. |
| |
| The GNU General Public License does not permit incorporating your |
| program into proprietary programs. If your program is a subroutine |
| library, you may consider it more useful to permit linking proprietary |
| applications with the library. If this is what you want to do, use the |
| GNU Lesser General Public License instead of this License. But first, |
| please read `http://www.gnu.org/philosophy/why-not-lgpl.html'. |
| |
| |
| File: gdb.info, Node: GNU Free Documentation License, Next: Index, Prev: Copying, Up: Top |
| |
| Appendix J GNU Free Documentation License |
| ***************************************** |
| |
| Version 1.3, 3 November 2008 |
| |
| Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. |
| `http://fsf.org/' |
| |
| Everyone is permitted to copy and distribute verbatim copies |
| of this license document, but changing it is not allowed. |
| |
| 0. PREAMBLE |
| |
| The purpose of this License is to make a manual, textbook, or other |
| functional and useful document "free" in the sense of freedom: to |
| assure everyone the effective freedom to copy and redistribute it, |
| with or without modifying it, either commercially or |
| noncommercially. Secondarily, this License preserves for the |
| author and publisher a way to get credit for their work, while not |
| being considered responsible for modifications made by others. |
| |
| This License is a kind of "copyleft", which means that derivative |
| works of the document must themselves be free in the same sense. |
| It complements the GNU General Public License, which is a copyleft |
| license designed for free software. |
| |
| We have designed this License in order to use it for manuals for |
| free software, because free software needs free documentation: a |
| free program should come with manuals providing the same freedoms |
| that the software does. But this License is not limited to |
| software manuals; it can be used for any textual work, regardless |
| of subject matter or whether it is published as a printed book. |
| We recommend this License principally for works whose purpose is |
| instruction or reference. |
| |
| 1. APPLICABILITY AND DEFINITIONS |
| |
| This License applies to any manual or other work, in any medium, |
| that contains a notice placed by the copyright holder saying it |
| can be distributed under the terms of this License. Such a notice |
| grants a world-wide, royalty-free license, unlimited in duration, |
| to use that work under the conditions stated herein. The |
| "Document", below, refers to any such manual or work. Any member |
| of the public is a licensee, and is addressed as "you". You |
| accept the license if you copy, modify or distribute the work in a |
| way requiring permission under copyright law. |
| |
| A "Modified Version" of the Document means any work containing the |
| Document or a portion of it, either copied verbatim, or with |
| modifications and/or translated into another language. |
| |
| A "Secondary Section" is a named appendix or a front-matter section |
| of the Document that deals exclusively with the relationship of the |
| publishers or authors of the Document to the Document's overall |
| subject (or to related matters) and contains nothing that could |
| fall directly within that overall subject. (Thus, if the Document |
| is in part a textbook of mathematics, a Secondary Section may not |
| explain any mathematics.) The relationship could be a matter of |
| historical connection with the subject or with related matters, or |
| of legal, commercial, philosophical, ethical or political position |
| regarding them. |
| |
| The "Invariant Sections" are certain Secondary Sections whose |
| titles are designated, as being those of Invariant Sections, in |
| the notice that says that the Document is released under this |
| License. If a section does not fit the above definition of |
| Secondary then it is not allowed to be designated as Invariant. |
| The Document may contain zero Invariant Sections. If the Document |
| does not identify any Invariant Sections then there are none. |
| |
| The "Cover Texts" are certain short passages of text that are |
| listed, as Front-Cover Texts or Back-Cover Texts, in the notice |
| that says that the Document is released under this License. A |
| Front-Cover Text may be at most 5 words, and a Back-Cover Text may |
| be at most 25 words. |
| |
| A "Transparent" copy of the Document means a machine-readable copy, |
| represented in a format whose specification is available to the |
| general public, that is suitable for revising the document |
| straightforwardly with generic text editors or (for images |
| composed of pixels) generic paint programs or (for drawings) some |
| widely available drawing editor, and that is suitable for input to |
| text formatters or for automatic translation to a variety of |
| formats suitable for input to text formatters. A copy made in an |
| otherwise Transparent file format whose markup, or absence of |
| markup, has been arranged to thwart or discourage subsequent |
| modification by readers is not Transparent. An image format is |
| not Transparent if used for any substantial amount of text. A |
| copy that is not "Transparent" is called "Opaque". |
| |
| Examples of suitable formats for Transparent copies include plain |
| ASCII without markup, Texinfo input format, LaTeX input format, |
| SGML or XML using a publicly available DTD, and |
| standard-conforming simple HTML, PostScript or PDF designed for |
| human modification. Examples of transparent image formats include |
| PNG, XCF and JPG. Opaque formats include proprietary formats that |
| can be read and edited only by proprietary word processors, SGML or |
| XML for which the DTD and/or processing tools are not generally |
| available, and the machine-generated HTML, PostScript or PDF |
| produced by some word processors for output purposes only. |
| |
| The "Title Page" means, for a printed book, the title page itself, |
| plus such following pages as are needed to hold, legibly, the |
| material this License requires to appear in the title page. For |
| works in formats which do not have any title page as such, "Title |
| Page" means the text near the most prominent appearance of the |
| work's title, preceding the beginning of the body of the text. |
| |
| The "publisher" means any person or entity that distributes copies |
| of the Document to the public. |
| |
| A section "Entitled XYZ" means a named subunit of the Document |
| whose title either is precisely XYZ or contains XYZ in parentheses |
| following text that translates XYZ in another language. (Here XYZ |
| stands for a specific section name mentioned below, such as |
| "Acknowledgements", "Dedications", "Endorsements", or "History".) |
| To "Preserve the Title" of such a section when you modify the |
| Document means that it remains a section "Entitled XYZ" according |
| to this definition. |
| |
| The Document may include Warranty Disclaimers next to the notice |
| which states that this License applies to the Document. These |
| Warranty Disclaimers are considered to be included by reference in |
| this License, but only as regards disclaiming warranties: any other |
| implication that these Warranty Disclaimers may have is void and |
| has no effect on the meaning of this License. |
| |
| 2. VERBATIM COPYING |
| |
| You may copy and distribute the Document in any medium, either |
| commercially or noncommercially, provided that this License, the |
| copyright notices, and the license notice saying this License |
| applies to the Document are reproduced in all copies, and that you |
| add no other conditions whatsoever to those of this License. You |
| may not use technical measures to obstruct or control the reading |
| or further copying of the copies you make or distribute. However, |
| you may accept compensation in exchange for copies. If you |
| distribute a large enough number of copies you must also follow |
| the conditions in section 3. |
| |
| You may also lend copies, under the same conditions stated above, |
| and you may publicly display copies. |
| |
| 3. COPYING IN QUANTITY |
| |
| If you publish printed copies (or copies in media that commonly |
| have printed covers) of the Document, numbering more than 100, and |
| the Document's license notice requires Cover Texts, you must |
| enclose the copies in covers that carry, clearly and legibly, all |
| these Cover Texts: Front-Cover Texts on the front cover, and |
| Back-Cover Texts on the back cover. Both covers must also clearly |
| and legibly identify you as the publisher of these copies. The |
| front cover must present the full title with all words of the |
| title equally prominent and visible. You may add other material |
| on the covers in addition. Copying with changes limited to the |
| covers, as long as they preserve the title of the Document and |
| satisfy these conditions, can be treated as verbatim copying in |
| other respects. |
| |
| If the required texts for either cover are too voluminous to fit |
| legibly, you should put the first ones listed (as many as fit |
| reasonably) on the actual cover, and continue the rest onto |
| adjacent pages. |
| |
| If you publish or distribute Opaque copies of the Document |
| numbering more than 100, you must either include a |
| machine-readable Transparent copy along with each Opaque copy, or |
| state in or with each Opaque copy a computer-network location from |
| which the general network-using public has access to download |
| using public-standard network protocols a complete Transparent |
| copy of the Document, free of added material. If you use the |
| latter option, you must take reasonably prudent steps, when you |
| begin distribution of Opaque copies in quantity, to ensure that |
| this Transparent copy will remain thus accessible at the stated |
| location until at least one year after the last time you |
| distribute an Opaque copy (directly or through your agents or |
| retailers) of that edition to the public. |
| |
| It is requested, but not required, that you contact the authors of |
| the Document well before redistributing any large number of |
| copies, to give them a chance to provide you with an updated |
| version of the Document. |
| |
| 4. MODIFICATIONS |
| |
| You may copy and distribute a Modified Version of the Document |
| under the conditions of sections 2 and 3 above, provided that you |
| release the Modified Version under precisely this License, with |
| the Modified Version filling the role of the Document, thus |
| licensing distribution and modification of the Modified Version to |
| whoever possesses a copy of it. In addition, you must do these |
| things in the Modified Version: |
| |
| A. Use in the Title Page (and on the covers, if any) a title |
| distinct from that of the Document, and from those of |
| previous versions (which should, if there were any, be listed |
| in the History section of the Document). You may use the |
| same title as a previous version if the original publisher of |
| that version gives permission. |
| |
| B. List on the Title Page, as authors, one or more persons or |
| entities responsible for authorship of the modifications in |
| the Modified Version, together with at least five of the |
| principal authors of the Document (all of its principal |
| authors, if it has fewer than five), unless they release you |
| from this requirement. |
| |
| C. State on the Title page the name of the publisher of the |
| Modified Version, as the publisher. |
| |
| D. Preserve all the copyright notices of the Document. |
| |
| E. Add an appropriate copyright notice for your modifications |
| adjacent to the other copyright notices. |
| |
| F. Include, immediately after the copyright notices, a license |
| notice giving the public permission to use the Modified |
| Version under the terms of this License, in the form shown in |
| the Addendum below. |
| |
| G. Preserve in that license notice the full lists of Invariant |
| Sections and required Cover Texts given in the Document's |
| license notice. |
| |
| H. Include an unaltered copy of this License. |
| |
| I. Preserve the section Entitled "History", Preserve its Title, |
| and add to it an item stating at least the title, year, new |
| authors, and publisher of the Modified Version as given on |
| the Title Page. If there is no section Entitled "History" in |
| the Document, create one stating the title, year, authors, |
| and publisher of the Document as given on its Title Page, |
| then add an item describing the Modified Version as stated in |
| the previous sentence. |
| |
| J. Preserve the network location, if any, given in the Document |
| for public access to a Transparent copy of the Document, and |
| likewise the network locations given in the Document for |
| previous versions it was based on. These may be placed in |
| the "History" section. You may omit a network location for a |
| work that was published at least four years before the |
| Document itself, or if the original publisher of the version |
| it refers to gives permission. |
| |
| K. For any section Entitled "Acknowledgements" or "Dedications", |
| Preserve the Title of the section, and preserve in the |
| section all the substance and tone of each of the contributor |
| acknowledgements and/or dedications given therein. |
| |
| L. Preserve all the Invariant Sections of the Document, |
| unaltered in their text and in their titles. Section numbers |
| or the equivalent are not considered part of the section |
| titles. |
| |
| M. Delete any section Entitled "Endorsements". Such a section |
| may not be included in the Modified Version. |
| |
| N. Do not retitle any existing section to be Entitled |
| "Endorsements" or to conflict in title with any Invariant |
| Section. |
| |
| O. Preserve any Warranty Disclaimers. |
| |
| If the Modified Version includes new front-matter sections or |
| appendices that qualify as Secondary Sections and contain no |
| material copied from the Document, you may at your option |
| designate some or all of these sections as invariant. To do this, |
| add their titles to the list of Invariant Sections in the Modified |
| Version's license notice. These titles must be distinct from any |
| other section titles. |
| |
| You may add a section Entitled "Endorsements", provided it contains |
| nothing but endorsements of your Modified Version by various |
| parties--for example, statements of peer review or that the text |
| has been approved by an organization as the authoritative |
| definition of a standard. |
| |
| You may add a passage of up to five words as a Front-Cover Text, |
| and a passage of up to 25 words as a Back-Cover Text, to the end |
| of the list of Cover Texts in the Modified Version. Only one |
| passage of Front-Cover Text and one of Back-Cover Text may be |
| added by (or through arrangements made by) any one entity. If the |
| Document already includes a cover text for the same cover, |
| previously added by you or by arrangement made by the same entity |
| you are acting on behalf of, you may not add another; but you may |
| replace the old one, on explicit permission from the previous |
| publisher that added the old one. |
| |
| The author(s) and publisher(s) of the Document do not by this |
| License give permission to use their names for publicity for or to |
| assert or imply endorsement of any Modified Version. |
| |
| 5. COMBINING DOCUMENTS |
| |
| You may combine the Document with other documents released under |
| this License, under the terms defined in section 4 above for |
| modified versions, provided that you include in the combination |
| all of the Invariant Sections of all of the original documents, |
| unmodified, and list them all as Invariant Sections of your |
| combined work in its license notice, and that you preserve all |
| their Warranty Disclaimers. |
| |
| The combined work need only contain one copy of this License, and |
| multiple identical Invariant Sections may be replaced with a single |
| copy. If there are multiple Invariant Sections with the same name |
| but different contents, make the title of each such section unique |
| by adding at the end of it, in parentheses, the name of the |
| original author or publisher of that section if known, or else a |
| unique number. Make the same adjustment to the section titles in |
| the list of Invariant Sections in the license notice of the |
| combined work. |
| |
| In the combination, you must combine any sections Entitled |
| "History" in the various original documents, forming one section |
| Entitled "History"; likewise combine any sections Entitled |
| "Acknowledgements", and any sections Entitled "Dedications". You |
| must delete all sections Entitled "Endorsements." |
| |
| 6. COLLECTIONS OF DOCUMENTS |
| |
| You may make a collection consisting of the Document and other |
| documents released under this License, and replace the individual |
| copies of this License in the various documents with a single copy |
| that is included in the collection, provided that you follow the |
| rules of this License for verbatim copying of each of the |
| documents in all other respects. |
| |
| You may extract a single document from such a collection, and |
| distribute it individually under this License, provided you insert |
| a copy of this License into the extracted document, and follow |
| this License in all other respects regarding verbatim copying of |
| that document. |
| |
| 7. AGGREGATION WITH INDEPENDENT WORKS |
| |
| A compilation of the Document or its derivatives with other |
| separate and independent documents or works, in or on a volume of |
| a storage or distribution medium, is called an "aggregate" if the |
| copyright resulting from the compilation is not used to limit the |
| legal rights of the compilation's users beyond what the individual |
| works permit. When the Document is included in an aggregate, this |
| License does not apply to the other works in the aggregate which |
| are not themselves derivative works of the Document. |
| |
| If the Cover Text requirement of section 3 is applicable to these |
| copies of the Document, then if the Document is less than one half |
| of the entire aggregate, the Document's Cover Texts may be placed |
| on covers that bracket the Document within the aggregate, or the |
| electronic equivalent of covers if the Document is in electronic |
| form. Otherwise they must appear on printed covers that bracket |
| the whole aggregate. |
| |
| 8. TRANSLATION |
| |
| Translation is considered a kind of modification, so you may |
| distribute translations of the Document under the terms of section |
| 4. Replacing Invariant Sections with translations requires special |
| permission from their copyright holders, but you may include |
| translations of some or all Invariant Sections in addition to the |
| original versions of these Invariant Sections. You may include a |
| translation of this License, and all the license notices in the |
| Document, and any Warranty Disclaimers, provided that you also |
| include the original English version of this License and the |
| original versions of those notices and disclaimers. In case of a |
| disagreement between the translation and the original version of |
| this License or a notice or disclaimer, the original version will |
| prevail. |
| |
| If a section in the Document is Entitled "Acknowledgements", |
| "Dedications", or "History", the requirement (section 4) to |
| Preserve its Title (section 1) will typically require changing the |
| actual title. |
| |
| 9. TERMINATION |
| |
| You may not copy, modify, sublicense, or distribute the Document |
| except as expressly provided under this License. Any attempt |
| otherwise to copy, modify, sublicense, or distribute it is void, |
| and will automatically terminate your rights under this License. |
| |
| However, if you cease all violation of this License, then your |
| license from a particular copyright holder is reinstated (a) |
| provisionally, unless and until the copyright holder explicitly |
| and finally terminates your license, and (b) permanently, if the |
| copyright holder fails to notify you of the violation by some |
| reasonable means prior to 60 days after the cessation. |
| |
| Moreover, your license from a particular copyright holder is |
| reinstated permanently if the copyright holder notifies you of the |
| violation by some reasonable means, this is the first time you have |
| received notice of violation of this License (for any work) from |
| that copyright holder, and you cure the violation prior to 30 days |
| after your receipt of the notice. |
| |
| Termination of your rights under this section does not terminate |
| the licenses of parties who have received copies or rights from |
| you under this License. If your rights have been terminated and |
| not permanently reinstated, receipt of a copy of some or all of |
| the same material does not give you any rights to use it. |
| |
| 10. FUTURE REVISIONS OF THIS LICENSE |
| |
| The Free Software Foundation may publish new, revised versions of |
| the GNU Free Documentation License from time to time. Such new |
| versions will be similar in spirit to the present version, but may |
| differ in detail to address new problems or concerns. See |
| `http://www.gnu.org/copyleft/'. |
| |
| Each version of the License is given a distinguishing version |
| number. If the Document specifies that a particular numbered |
| version of this License "or any later version" applies to it, you |
| have the option of following the terms and conditions either of |
| that specified version or of any later version that has been |
| published (not as a draft) by the Free Software Foundation. If |
| the Document does not specify a version number of this License, |
| you may choose any version ever published (not as a draft) by the |
| Free Software Foundation. If the Document specifies that a proxy |
| can decide which future versions of this License can be used, that |
| proxy's public statement of acceptance of a version permanently |
| authorizes you to choose that version for the Document. |
| |
| 11. RELICENSING |
| |
| "Massive Multiauthor Collaboration Site" (or "MMC Site") means any |
| World Wide Web server that publishes copyrightable works and also |
| provides prominent facilities for anybody to edit those works. A |
| public wiki that anybody can edit is an example of such a server. |
| A "Massive Multiauthor Collaboration" (or "MMC") contained in the |
| site means any set of copyrightable works thus published on the MMC |
| site. |
| |
| "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 |
| license published by Creative Commons Corporation, a not-for-profit |
| corporation with a principal place of business in San Francisco, |
| California, as well as future copyleft versions of that license |
| published by that same organization. |
| |
| "Incorporate" means to publish or republish a Document, in whole or |
| in part, as part of another Document. |
| |
| An MMC is "eligible for relicensing" if it is licensed under this |
| License, and if all works that were first published under this |
| License somewhere other than this MMC, and subsequently |
| incorporated in whole or in part into the MMC, (1) had no cover |
| texts or invariant sections, and (2) were thus incorporated prior |
| to November 1, 2008. |
| |
| The operator of an MMC Site may republish an MMC contained in the |
| site under CC-BY-SA on the same site at any time before August 1, |
| 2009, provided the MMC is eligible for relicensing. |
| |
| |
| ADDENDUM: How to use this License for your documents |
| ==================================================== |
| |
| To use this License in a document you have written, include a copy of |
| the License in the document and put the following copyright and license |
| notices just after the title page: |
| |
| Copyright (C) YEAR YOUR NAME. |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 |
| or any later version published by the Free Software Foundation; |
| with no Invariant Sections, no Front-Cover Texts, and no Back-Cover |
| Texts. A copy of the license is included in the section entitled ``GNU |
| Free Documentation License''. |
| |
| If you have Invariant Sections, Front-Cover Texts and Back-Cover |
| Texts, replace the "with...Texts." line with this: |
| |
| with the Invariant Sections being LIST THEIR TITLES, with |
| the Front-Cover Texts being LIST, and with the Back-Cover Texts |
| being LIST. |
| |
| If you have Invariant Sections without Cover Texts, or some other |
| combination of the three, merge those two alternatives to suit the |
| situation. |
| |
| If your document contains nontrivial examples of program code, we |
| recommend releasing these examples in parallel under your choice of |
| free software license, such as the GNU General Public License, to |
| permit their use in free software. |
| |