OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-old/] [gdb-6.8/] [gdb/] [doc/] [annotate.info] - Blame information for rev 840

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 24 jeremybenn
This is annotate.info, produced by makeinfo version 4.8 from
2
../.././gdb/doc/annotate.texinfo.
3
 
4
INFO-DIR-SECTION Software development
5
START-INFO-DIR-ENTRY
6
* Annotate: (annotate).                 The obsolete annotation interface.
7
END-INFO-DIR-ENTRY
8
 
9
   This file documents GDB's obsolete annotations.
10
 
11
   Copyright (C) 1994, 1995, 2000, 2001, 2003 Free Software Foundation,
12
Inc.
13
 
14
   Permission is granted to copy, distribute and/or modify this document
15
under the terms of the GNU Free Documentation License, Version 1.1 or
16
any later version published by the Free Software Foundation; with no
17
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
18
Texts.  A copy of the license is included in the section entitled "GNU
19
Free Documentation License".
20
 
21

22
File: annotate.info,  Node: Top,  Next: Annotations Overview,  Up: (dir)
23
 
24
GDB Annotations
25
***************
26
 
27
This document describes the obsolete level two annotation interface
28
implemented in older GDB versions.
29
 
30
* Menu:
31
 
32
* Annotations Overview::  What annotations are; the general syntax.
33
* Limitations::           Limitations of the annotation interface.
34
* Migrating to GDB/MI::   Migrating to GDB/MI
35
* Server Prefix::       Issuing a command without affecting user state.
36
* Value Annotations::   Values are marked as such.
37
* Frame Annotations::   Stack frames are annotated.
38
* Displays::            GDB can be told to display something periodically.
39
* Prompting::           Annotations marking GDB's need for input.
40
* Errors::              Annotations for error messages.
41
* Breakpoint Info::     Information on breakpoints.
42
* Invalidation::        Some annotations describe things now invalid.
43
* Annotations for Running::
44
                        Whether the program is running, how it stopped, etc.
45
* Source Annotations::  Annotations describing source code.
46
 
47
* GNU Free Documentation License::
48
 
49

50
File: annotate.info,  Node: Annotations Overview,  Next: Limitations,  Prev: Top,  Up: Top
51
 
52
1 What is an Annotation?
53
************************
54
 
55
To produce obsolete level two annotations, start GDB with the
56
`--annotate=2' option.
57
 
58
   Annotations start with a newline character, two `control-z'
59
characters, and the name of the annotation.  If there is no additional
60
information associated with this annotation, the name of the annotation
61
is followed immediately by a newline.  If there is additional
62
information, the name of the annotation is followed by a space, the
63
additional information, and a newline.  The additional information
64
cannot contain newline characters.
65
 
66
   Any output not beginning with a newline and two `control-z'
67
characters denotes literal output from GDB.  Currently there is no need
68
for GDB to output a newline followed by two `control-z' characters, but
69
if there was such a need, the annotations could be extended with an
70
`escape' annotation which means those three characters as output.
71
 
72
   A simple example of starting up GDB with annotations is:
73
 
74
     $ gdb --annotate=2
75
     GNU GDB 5.0
76
     Copyright 2000 Free Software Foundation, Inc.
77
     GDB is free software, covered by the GNU General Public License,
78
     and you are welcome to change it and/or distribute copies of it
79
     under certain conditions.
80
     Type "show copying" to see the conditions.
81
     There is absolutely no warranty for GDB.  Type "show warranty"
82
     for details.
83
     This GDB was configured as "sparc-sun-sunos4.1.3"
84
 
85
     ^Z^Zpre-prompt
86
     (gdb)
87
     ^Z^Zprompt
88
     quit
89
 
90
     ^Z^Zpost-prompt
91
     $
92
 
93
   Here `quit' is input to GDB; the rest is output from GDB.  The three
94
lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are
95
annotations; the rest is output from GDB.
96
 
97

98
File: annotate.info,  Node: Limitations,  Next: Migrating to GDB/MI,  Prev: Annotations Overview,  Up: Top
99
 
100
2 Limitations of the Annotation Interface
101
*****************************************
102
 
103
The level two annotations mechanism is known to have a number of
104
technical and architectural limitations.  As a consequence, in 2001,
105
with the release of GDB 5.1 and the addition of GDB/MI, the annotation
106
interface was marked as deprecated.
107
 
108
   This chapter discusses the known problems.
109
 
110
2.1 Dependant on CLI output
111
===========================
112
 
113
The annotation interface works by interspersing markups with GDB normal
114
command-line interpreter output.  Unfortunately, this makes the
115
annotation client dependant on not just the annotations, but also the
116
CLI output.  This is because the client is forced to assume that
117
specific GDB commands provide specific information.  Any change to
118
GDB's CLI output modifies or removes that information and,
119
consequently, likely breaks the client.
120
 
121
   Since the GDB/MI output is independent of the CLI, it does not have
122
this problem.
123
 
124
2.2 Scalability
125
===============
126
 
127
The annotation interface relies on value annotations (*note Value
128
Annotations::) and the display mechanism as a way of obtaining
129
up-to-date value information.  These mechanisms are not scalable.
130
 
131
   In a graphical environment, where many values can be displayed
132
simultaneously, a serious performance problem occurs when the client
133
tries to first extract from GDB, and then re-display, all those values.
134
The client should instead only request and update the values that
135
changed.
136
 
137
   The GDB/MI Variable Objects provide just that mechanism.
138
 
139
2.3 Correctness
140
===============
141
 
142
The annotation interface assumes that a variable's value can only be
143
changed when the target is running.  This assumption is not correct.  A
144
single assignment to a single variable can result in the entire target,
145
and all displayed values, needing an update.
146
 
147
   The GDB/MI Variable Objects include a mechanism for efficiently
148
reporting such changes.
149
 
150
2.4 Reliability
151
===============
152
 
153
The GDB/MI interface includes a dedicated test directory
154
(`gdb/gdb.mi'), and any addition or fix to GDB/MI must include
155
testsuite changes.
156
 
157
2.5 Maintainability
158
===================
159
 
160
The annotation mechanism was implemented by interspersing CLI print
161
statements with various annotations.  As a consequence, any CLI output
162
change can alter the annotation output.
163
 
164
   Since the GDB/MI output is independent of the CLI, and the GDB/MI is
165
increasingly implemented independent of the CLI code, its long term
166
maintenance is much easier.
167
 
168

169
File: annotate.info,  Node: Migrating to GDB/MI,  Next: Server Prefix,  Prev: Limitations,  Up: Top
170
 
171
3 Migrating to GDB/MI
172
*********************
173
 
174
By using the `interp mi' command, it is possible for annotation clients
175
to invoke GDB/MI commands, and hence access the GDB/MI.  By doing this,
176
existing annotation clients have a migration path from this obsolete
177
interface to GDB/MI.
178
 
179

180
File: annotate.info,  Node: Server Prefix,  Next: Value Annotations,  Prev: Migrating to GDB/MI,  Up: Top
181
 
182
4 The Server Prefix
183
*******************
184
 
185
To issue a command to GDB without affecting certain aspects of the
186
state which is seen by users, prefix it with `server '.  This means
187
that this command will not affect the command history, nor will it
188
affect GDB's notion of which command to repeat if  is pressed on a
189
line by itself.
190
 
191
   The server prefix does not affect the recording of values into the
192
value history; to print a value without recording it into the value
193
history, use the `output' command instead of the `print' command.
194
 
195

196
File: annotate.info,  Node: Value Annotations,  Next: Frame Annotations,  Prev: Server Prefix,  Up: Top
197
 
198
5 Values
199
********
200
 
201
_Value Annotations have been removed.  GDB/MI instead provides Variable
202
Objects._
203
 
204
   When a value is printed in various contexts, GDB uses annotations to
205
delimit the value from the surrounding text.
206
 
207
   If a value is printed using `print' and added to the value history,
208
the annotation looks like
209
 
210
     ^Z^Zvalue-history-begin HISTORY-NUMBER VALUE-FLAGS
211
     HISTORY-STRING
212
     ^Z^Zvalue-history-value
213
     THE-VALUE
214
     ^Z^Zvalue-history-end
215
 
216
where HISTORY-NUMBER is the number it is getting in the value history,
217
HISTORY-STRING is a string, such as `$5 = ', which introduces the value
218
to the user, THE-VALUE is the output corresponding to the value itself,
219
and VALUE-FLAGS is `*' for a value which can be dereferenced and `-'
220
for a value which cannot.
221
 
222
   If the value is not added to the value history (it is an invalid
223
float or it is printed with the `output' command), the annotation is
224
similar:
225
 
226
     ^Z^Zvalue-begin VALUE-FLAGS
227
     THE-VALUE
228
     ^Z^Zvalue-end
229
 
230
   When GDB prints an argument to a function (for example, in the output
231
from the `backtrace' command), it annotates it as follows:
232
 
233
     ^Z^Zarg-begin
234
     ARGUMENT-NAME
235
     ^Z^Zarg-name-end
236
     SEPARATOR-STRING
237
     ^Z^Zarg-value VALUE-FLAGS
238
     THE-VALUE
239
     ^Z^Zarg-end
240
 
241
where ARGUMENT-NAME is the name of the argument, SEPARATOR-STRING is
242
text which separates the name from the value for the user's benefit
243
(such as `='), and VALUE-FLAGS and THE-VALUE have the same meanings as
244
in a `value-history-begin' annotation.
245
 
246
   When printing a structure, GDB annotates it as follows:
247
 
248
     ^Z^Zfield-begin VALUE-FLAGS
249
     FIELD-NAME
250
     ^Z^Zfield-name-end
251
     SEPARATOR-STRING
252
     ^Z^Zfield-value
253
     THE-VALUE
254
     ^Z^Zfield-end
255
 
256
where FIELD-NAME is the name of the field, SEPARATOR-STRING is text
257
which separates the name from the value for the user's benefit (such as
258
`='), and VALUE-FLAGS and THE-VALUE have the same meanings as in a
259
`value-history-begin' annotation.
260
 
261
   When printing an array, GDB annotates it as follows:
262
 
263
     ^Z^Zarray-section-begin ARRAY-INDEX VALUE-FLAGS
264
 
265
where ARRAY-INDEX is the index of the first element being annotated and
266
VALUE-FLAGS has the same meaning as in a `value-history-begin'
267
annotation.  This is followed by any number of elements, where is
268
element can be either a single element:
269
 
270
     `,' WHITESPACE         ; omitted for the first element
271
     THE-VALUE
272
     ^Z^Zelt
273
 
274
   or a repeated element
275
 
276
     `,' WHITESPACE         ; omitted for the first element
277
     THE-VALUE
278
     ^Z^Zelt-rep NUMBER-OF-REPETITIONS
279
     REPETITION-STRING
280
     ^Z^Zelt-rep-end
281
 
282
   In both cases, THE-VALUE is the output for the value of the element
283
and WHITESPACE can contain spaces, tabs, and newlines.  In the repeated
284
case, NUMBER-OF-REPETITIONS is the number of consecutive array elements
285
which contain that value, and REPETITION-STRING is a string which is
286
designed to convey to the user that repetition is being depicted.
287
 
288
   Once all the array elements have been output, the array annotation is
289
ended with
290
 
291
     ^Z^Zarray-section-end
292
 
293

294
File: annotate.info,  Node: Frame Annotations,  Next: Displays,  Prev: Value Annotations,  Up: Top
295
 
296
6 Frames
297
********
298
 
299
_Value Annotations have been removed.  GDB/MI instead provides a number
300
of frame commands._
301
 
302
   _Frame annotations are no longer available.  The GDB/MI provides
303
`-stack-list-arguments', `-stack-list-locals', and `-stack-list-frames'
304
commands._
305
 
306
   Whenever GDB prints a frame, it annotates it.  For example, this
307
applies to frames printed when GDB stops, output from commands such as
308
`backtrace' or `up', etc.
309
 
310
   The frame annotation begins with
311
 
312
     ^Z^Zframe-begin LEVEL ADDRESS
313
     LEVEL-STRING
314
 
315
where LEVEL is the number of the frame (0 is the innermost frame, and
316
other frames have positive numbers), ADDRESS is the address of the code
317
executing in that frame, and LEVEL-STRING is a string designed to
318
convey the level to the user.  ADDRESS is in the form `0x' followed by
319
one or more lowercase hex digits (note that this does not depend on the
320
language).  The frame ends with
321
 
322
     ^Z^Zframe-end
323
 
324
   Between these annotations is the main body of the frame, which can
325
consist of
326
 
327
   *      ^Z^Zfunction-call
328
          FUNCTION-CALL-STRING
329
 
330
     where FUNCTION-CALL-STRING is text designed to convey to the user
331
     that this frame is associated with a function call made by GDB to a
332
     function in the program being debugged.
333
 
334
   *      ^Z^Zsignal-handler-caller
335
          SIGNAL-HANDLER-CALLER-STRING
336
 
337
     where SIGNAL-HANDLER-CALLER-STRING is text designed to convey to
338
     the user that this frame is associated with whatever mechanism is
339
     used by this operating system to call a signal handler (it is the
340
     frame which calls the signal handler, not the frame for the signal
341
     handler itself).
342
 
343
   * A normal frame.
344
 
345
     This can optionally (depending on whether this is thought of as
346
     interesting information for the user to see) begin with
347
 
348
          ^Z^Zframe-address
349
          ADDRESS
350
          ^Z^Zframe-address-end
351
          SEPARATOR-STRING
352
 
353
     where ADDRESS is the address executing in the frame (the same
354
     address as in the `frame-begin' annotation, but printed in a form
355
     which is intended for user consumption--in particular, the syntax
356
     varies depending on the language), and SEPARATOR-STRING is a string
357
     intended to separate this address from what follows for the user's
358
     benefit.
359
 
360
     Then comes
361
 
362
          ^Z^Zframe-function-name
363
          FUNCTION-NAME
364
          ^Z^Zframe-args
365
          ARGUMENTS
366
 
367
     where FUNCTION-NAME is the name of the function executing in the
368
     frame, or `??' if not known, and ARGUMENTS are the arguments to
369
     the frame, with parentheses around them (each argument is annotated
370
     individually as well, *note Value Annotations::).
371
 
372
     If source information is available, a reference to it is then
373
     printed:
374
 
375
          ^Z^Zframe-source-begin
376
          SOURCE-INTRO-STRING
377
          ^Z^Zframe-source-file
378
          FILENAME
379
          ^Z^Zframe-source-file-end
380
          :
381
          ^Z^Zframe-source-line
382
          LINE-NUMBER
383
          ^Z^Zframe-source-end
384
 
385
     where SOURCE-INTRO-STRING separates for the user's benefit the
386
     reference from the text which precedes it, FILENAME is the name of
387
     the source file, and LINE-NUMBER is the line number within that
388
     file (the first line is line 1).
389
 
390
     If GDB prints some information about where the frame is from (which
391
     library, which load segment, etc.; currently only done on the
392
     RS/6000), it is annotated with
393
 
394
          ^Z^Zframe-where
395
          INFORMATION
396
 
397
     Then, if source is to actually be displayed for this frame (for
398
     example, this is not true for output from the `backtrace'
399
     command), then a `source' annotation (*note Source Annotations::)
400
     is displayed.  Unlike most annotations, this is output instead of
401
     the normal text which would be output, not in addition.
402
 
403

404
File: annotate.info,  Node: Displays,  Next: Prompting,  Prev: Frame Annotations,  Up: Top
405
 
406
7 Displays
407
**********
408
 
409
_Display Annotations have been removed.  GDB/MI instead provides
410
Variable Objects._
411
 
412
   When GDB is told to display something using the `display' command,
413
the results of the display are annotated:
414
 
415
     ^Z^Zdisplay-begin
416
     NUMBER
417
     ^Z^Zdisplay-number-end
418
     NUMBER-SEPARATOR
419
     ^Z^Zdisplay-format
420
     FORMAT
421
     ^Z^Zdisplay-expression
422
     EXPRESSION
423
     ^Z^Zdisplay-expression-end
424
     EXPRESSION-SEPARATOR
425
     ^Z^Zdisplay-value
426
     VALUE
427
     ^Z^Zdisplay-end
428
 
429
where NUMBER is the number of the display, NUMBER-SEPARATOR is intended
430
to separate the number from what follows for the user, FORMAT includes
431
information such as the size, format, or other information about how
432
the value is being displayed, EXPRESSION is the expression being
433
displayed, EXPRESSION-SEPARATOR is intended to separate the expression
434
from the text that follows for the user, and VALUE is the actual value
435
being displayed.
436
 
437

438
File: annotate.info,  Node: Prompting,  Next: Errors,  Prev: Displays,  Up: Top
439
 
440
8 Annotation for GDB Input
441
**************************
442
 
443
When GDB prompts for input, it annotates this fact so it is possible to
444
know when to send output, when the output from a given command is over,
445
etc.
446
 
447
   Different kinds of input each have a different "input type".  Each
448
input type has three annotations: a `pre-' annotation, which denotes
449
the beginning of any prompt which is being output, a plain annotation,
450
which denotes the end of the prompt, and then a `post-' annotation
451
which denotes the end of any echo which may (or may not) be associated
452
with the input.  For example, the `prompt' input type features the
453
following annotations:
454
 
455
     ^Z^Zpre-prompt
456
     ^Z^Zprompt
457
     ^Z^Zpost-prompt
458
 
459
   The input types are
460
 
461
`prompt'
462
     When GDB is prompting for a command (the main GDB prompt).
463
 
464
`commands'
465
     When GDB prompts for a set of commands, like in the `commands'
466
     command.  The annotations are repeated for each command which is
467
     input.
468
 
469
`overload-choice'
470
     When GDB wants the user to select between various overloaded
471
     functions.
472
 
473
`query'
474
     When GDB wants the user to confirm a potentially dangerous
475
     operation.
476
 
477
`prompt-for-continue'
478
     When GDB is asking the user to press return to continue.  Note:
479
     Don't expect this to work well; instead use `set height 0' to
480
     disable prompting.  This is because the counting of lines is buggy
481
     in the presence of annotations.
482
 
483

484
File: annotate.info,  Node: Errors,  Next: Breakpoint Info,  Prev: Prompting,  Up: Top
485
 
486
9 Errors
487
********
488
 
489
     ^Z^Zquit
490
 
491
   This annotation occurs right before GDB responds to an interrupt.
492
 
493
     ^Z^Zerror
494
 
495
   This annotation occurs right before GDB responds to an error.
496
 
497
   Quit and error annotations indicate that any annotations which GDB
498
was in the middle of may end abruptly.  For example, if a
499
`value-history-begin' annotation is followed by a `error', one cannot
500
expect to receive the matching `value-history-end'.  One cannot expect
501
not to receive it either, however; an error annotation does not
502
necessarily mean that GDB is immediately returning all the way to the
503
top level.
504
 
505
   A quit or error annotation may be preceded by
506
 
507
     ^Z^Zerror-begin
508
 
509
   Any output between that and the quit or error annotation is the error
510
message.
511
 
512
   Warning messages are not yet annotated.
513
 
514

515
File: annotate.info,  Node: Breakpoint Info,  Next: Invalidation,  Prev: Errors,  Up: Top
516
 
517
10 Information on Breakpoints
518
*****************************
519
 
520
_Breakpoint Annotations have been removed.  GDB/MI instead provides
521
breakpoint commands._
522
 
523
   The output from the `info breakpoints' command is annotated as
524
follows:
525
 
526
     ^Z^Zbreakpoints-headers
527
     HEADER-ENTRY
528
     ^Z^Zbreakpoints-table
529
 
530
where HEADER-ENTRY has the same syntax as an entry (see below) but
531
instead of containing data, it contains strings which are intended to
532
convey the meaning of each field to the user.  This is followed by any
533
number of entries.  If a field does not apply for this entry, it is
534
omitted.  Fields may contain trailing whitespace.  Each entry consists
535
of:
536
 
537
     ^Z^Zrecord
538
     ^Z^Zfield 0
539
     NUMBER
540
     ^Z^Zfield 1
541
     TYPE
542
     ^Z^Zfield 2
543
     DISPOSITION
544
     ^Z^Zfield 3
545
     ENABLE
546
     ^Z^Zfield 4
547
     ADDRESS
548
     ^Z^Zfield 5
549
     WHAT
550
     ^Z^Zfield 6
551
     FRAME
552
     ^Z^Zfield 7
553
     CONDITION
554
     ^Z^Zfield 8
555
     IGNORE-COUNT
556
     ^Z^Zfield 9
557
     COMMANDS
558
 
559
   Note that ADDRESS is intended for user consumption--the syntax
560
varies depending on the language.
561
 
562
   The output ends with
563
 
564
     ^Z^Zbreakpoints-table-end
565
 
566

567
File: annotate.info,  Node: Invalidation,  Next: Annotations for Running,  Prev: Breakpoint Info,  Up: Top
568
 
569
11 Invalidation Notices
570
***********************
571
 
572
The following annotations say that certain pieces of state may have
573
changed.
574
 
575
`^Z^Zframes-invalid'
576
     The frames (for example, output from the `backtrace' command) may
577
     have changed.
578
 
579
`^Z^Zbreakpoints-invalid'
580
     The breakpoints may have changed.  For example, the user just
581
     added or deleted a breakpoint.
582
 
583

584
File: annotate.info,  Node: Annotations for Running,  Next: Source Annotations,  Prev: Invalidation,  Up: Top
585
 
586
12 Running the Program
587
**********************
588
 
589
When the program starts executing due to a GDB command such as `step'
590
or `continue',
591
 
592
     ^Z^Zstarting
593
 
594
   is output.  When the program stops,
595
 
596
     ^Z^Zstopped
597
 
598
   is output.  Before the `stopped' annotation, a variety of
599
annotations describe how the program stopped.
600
 
601
`^Z^Zexited EXIT-STATUS'
602
     The program exited, and EXIT-STATUS is the exit status (zero for
603
     successful exit, otherwise nonzero).
604
 
605
`^Z^Zsignalled'
606
     The program exited with a signal.  After the `^Z^Zsignalled', the
607
     annotation continues:
608
 
609
          INTRO-TEXT
610
          ^Z^Zsignal-name
611
          NAME
612
          ^Z^Zsignal-name-end
613
          MIDDLE-TEXT
614
          ^Z^Zsignal-string
615
          STRING
616
          ^Z^Zsignal-string-end
617
          END-TEXT
618
 
619
     where NAME is the name of the signal, such as `SIGILL' or
620
     `SIGSEGV', and STRING is the explanation of the signal, such as
621
     `Illegal Instruction' or `Segmentation fault'.  INTRO-TEXT,
622
     MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no
623
     particular format.
624
 
625
`^Z^Zsignal'
626
     The syntax of this annotation is just like `signalled', but GDB is
627
     just saying that the program received the signal, not that it was
628
     terminated with it.
629
 
630
`^Z^Zbreakpoint NUMBER'
631
     The program hit breakpoint number NUMBER.
632
 
633
`^Z^Zwatchpoint NUMBER'
634
     The program hit watchpoint number NUMBER.
635
 
636

637
File: annotate.info,  Node: Source Annotations,  Next: GNU Free Documentation License,  Prev: Annotations for Running,  Up: Top
638
 
639
13 Displaying Source
640
********************
641
 
642
The following annotation is used instead of displaying source code:
643
 
644
     ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
645
 
646
   where FILENAME is an absolute file name indicating which source
647
file, LINE is the line number within that file (where 1 is the first
648
line in the file), CHARACTER is the character position within the file
649
(where 0 is the first character in the file) (for most debug formats
650
this will necessarily point to the beginning of a line), MIDDLE is
651
`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at
652
the beginning of the line, and ADDR is the address in the target
653
program associated with the source which is being displayed.  ADDR is
654
in the form `0x' followed by one or more lowercase hex digits (note
655
that this does not depend on the language).
656
 
657

658
File: annotate.info,  Node: GNU Free Documentation License,  Prev: Source Annotations,  Up: Top
659
 
660
14 GNU Free Documentation License
661
*********************************
662
 
663
                      Version 1.2, November 2002
664
 
665
     Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
666
     51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
667
 
668
     Everyone is permitted to copy and distribute verbatim copies
669
     of this license document, but changing it is not allowed.
670
 
671
  0. PREAMBLE
672
 
673
     The purpose of this License is to make a manual, textbook, or other
674
     functional and useful document "free" in the sense of freedom: to
675
     assure everyone the effective freedom to copy and redistribute it,
676
     with or without modifying it, either commercially or
677
     noncommercially.  Secondarily, this License preserves for the
678
     author and publisher a way to get credit for their work, while not
679
     being considered responsible for modifications made by others.
680
 
681
     This License is a kind of "copyleft", which means that derivative
682
     works of the document must themselves be free in the same sense.
683
     It complements the GNU General Public License, which is a copyleft
684
     license designed for free software.
685
 
686
     We have designed this License in order to use it for manuals for
687
     free software, because free software needs free documentation: a
688
     free program should come with manuals providing the same freedoms
689
     that the software does.  But this License is not limited to
690
     software manuals; it can be used for any textual work, regardless
691
     of subject matter or whether it is published as a printed book.
692
     We recommend this License principally for works whose purpose is
693
     instruction or reference.
694
 
695
  1. APPLICABILITY AND DEFINITIONS
696
 
697
     This License applies to any manual or other work, in any medium,
698
     that contains a notice placed by the copyright holder saying it
699
     can be distributed under the terms of this License.  Such a notice
700
     grants a world-wide, royalty-free license, unlimited in duration,
701
     to use that work under the conditions stated herein.  The
702
     "Document", below, refers to any such manual or work.  Any member
703
     of the public is a licensee, and is addressed as "you".  You
704
     accept the license if you copy, modify or distribute the work in a
705
     way requiring permission under copyright law.
706
 
707
     A "Modified Version" of the Document means any work containing the
708
     Document or a portion of it, either copied verbatim, or with
709
     modifications and/or translated into another language.
710
 
711
     A "Secondary Section" is a named appendix or a front-matter section
712
     of the Document that deals exclusively with the relationship of the
713
     publishers or authors of the Document to the Document's overall
714
     subject (or to related matters) and contains nothing that could
715
     fall directly within that overall subject.  (Thus, if the Document
716
     is in part a textbook of mathematics, a Secondary Section may not
717
     explain any mathematics.)  The relationship could be a matter of
718
     historical connection with the subject or with related matters, or
719
     of legal, commercial, philosophical, ethical or political position
720
     regarding them.
721
 
722
     The "Invariant Sections" are certain Secondary Sections whose
723
     titles are designated, as being those of Invariant Sections, in
724
     the notice that says that the Document is released under this
725
     License.  If a section does not fit the above definition of
726
     Secondary then it is not allowed to be designated as Invariant.
727
     The Document may contain zero Invariant Sections.  If the Document
728
     does not identify any Invariant Sections then there are none.
729
 
730
     The "Cover Texts" are certain short passages of text that are
731
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
732
     that says that the Document is released under this License.  A
733
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
734
     be at most 25 words.
735
 
736
     A "Transparent" copy of the Document means a machine-readable copy,
737
     represented in a format whose specification is available to the
738
     general public, that is suitable for revising the document
739
     straightforwardly with generic text editors or (for images
740
     composed of pixels) generic paint programs or (for drawings) some
741
     widely available drawing editor, and that is suitable for input to
742
     text formatters or for automatic translation to a variety of
743
     formats suitable for input to text formatters.  A copy made in an
744
     otherwise Transparent file format whose markup, or absence of
745
     markup, has been arranged to thwart or discourage subsequent
746
     modification by readers is not Transparent.  An image format is
747
     not Transparent if used for any substantial amount of text.  A
748
     copy that is not "Transparent" is called "Opaque".
749
 
750
     Examples of suitable formats for Transparent copies include plain
751
     ASCII without markup, Texinfo input format, LaTeX input format,
752
     SGML or XML using a publicly available DTD, and
753
     standard-conforming simple HTML, PostScript or PDF designed for
754
     human modification.  Examples of transparent image formats include
755
     PNG, XCF and JPG.  Opaque formats include proprietary formats that
756
     can be read and edited only by proprietary word processors, SGML or
757
     XML for which the DTD and/or processing tools are not generally
758
     available, and the machine-generated HTML, PostScript or PDF
759
     produced by some word processors for output purposes only.
760
 
761
     The "Title Page" means, for a printed book, the title page itself,
762
     plus such following pages as are needed to hold, legibly, the
763
     material this License requires to appear in the title page.  For
764
     works in formats which do not have any title page as such, "Title
765
     Page" means the text near the most prominent appearance of the
766
     work's title, preceding the beginning of the body of the text.
767
 
768
     A section "Entitled XYZ" means a named subunit of the Document
769
     whose title either is precisely XYZ or contains XYZ in parentheses
770
     following text that translates XYZ in another language.  (Here XYZ
771
     stands for a specific section name mentioned below, such as
772
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
773
     To "Preserve the Title" of such a section when you modify the
774
     Document means that it remains a section "Entitled XYZ" according
775
     to this definition.
776
 
777
     The Document may include Warranty Disclaimers next to the notice
778
     which states that this License applies to the Document.  These
779
     Warranty Disclaimers are considered to be included by reference in
780
     this License, but only as regards disclaiming warranties: any other
781
     implication that these Warranty Disclaimers may have is void and
782
     has no effect on the meaning of this License.
783
 
784
  2. VERBATIM COPYING
785
 
786
     You may copy and distribute the Document in any medium, either
787
     commercially or noncommercially, provided that this License, the
788
     copyright notices, and the license notice saying this License
789
     applies to the Document are reproduced in all copies, and that you
790
     add no other conditions whatsoever to those of this License.  You
791
     may not use technical measures to obstruct or control the reading
792
     or further copying of the copies you make or distribute.  However,
793
     you may accept compensation in exchange for copies.  If you
794
     distribute a large enough number of copies you must also follow
795
     the conditions in section 3.
796
 
797
     You may also lend copies, under the same conditions stated above,
798
     and you may publicly display copies.
799
 
800
  3. COPYING IN QUANTITY
801
 
802
     If you publish printed copies (or copies in media that commonly
803
     have printed covers) of the Document, numbering more than 100, and
804
     the Document's license notice requires Cover Texts, you must
805
     enclose the copies in covers that carry, clearly and legibly, all
806
     these Cover Texts: Front-Cover Texts on the front cover, and
807
     Back-Cover Texts on the back cover.  Both covers must also clearly
808
     and legibly identify you as the publisher of these copies.  The
809
     front cover must present the full title with all words of the
810
     title equally prominent and visible.  You may add other material
811
     on the covers in addition.  Copying with changes limited to the
812
     covers, as long as they preserve the title of the Document and
813
     satisfy these conditions, can be treated as verbatim copying in
814
     other respects.
815
 
816
     If the required texts for either cover are too voluminous to fit
817
     legibly, you should put the first ones listed (as many as fit
818
     reasonably) on the actual cover, and continue the rest onto
819
     adjacent pages.
820
 
821
     If you publish or distribute Opaque copies of the Document
822
     numbering more than 100, you must either include a
823
     machine-readable Transparent copy along with each Opaque copy, or
824
     state in or with each Opaque copy a computer-network location from
825
     which the general network-using public has access to download
826
     using public-standard network protocols a complete Transparent
827
     copy of the Document, free of added material.  If you use the
828
     latter option, you must take reasonably prudent steps, when you
829
     begin distribution of Opaque copies in quantity, to ensure that
830
     this Transparent copy will remain thus accessible at the stated
831
     location until at least one year after the last time you
832
     distribute an Opaque copy (directly or through your agents or
833
     retailers) of that edition to the public.
834
 
835
     It is requested, but not required, that you contact the authors of
836
     the Document well before redistributing any large number of
837
     copies, to give them a chance to provide you with an updated
838
     version of the Document.
839
 
840
  4. MODIFICATIONS
841
 
842
     You may copy and distribute a Modified Version of the Document
843
     under the conditions of sections 2 and 3 above, provided that you
844
     release the Modified Version under precisely this License, with
845
     the Modified Version filling the role of the Document, thus
846
     licensing distribution and modification of the Modified Version to
847
     whoever possesses a copy of it.  In addition, you must do these
848
     things in the Modified Version:
849
 
850
       A. Use in the Title Page (and on the covers, if any) a title
851
          distinct from that of the Document, and from those of
852
          previous versions (which should, if there were any, be listed
853
          in the History section of the Document).  You may use the
854
          same title as a previous version if the original publisher of
855
          that version gives permission.
856
 
857
       B. List on the Title Page, as authors, one or more persons or
858
          entities responsible for authorship of the modifications in
859
          the Modified Version, together with at least five of the
860
          principal authors of the Document (all of its principal
861
          authors, if it has fewer than five), unless they release you
862
          from this requirement.
863
 
864
       C. State on the Title page the name of the publisher of the
865
          Modified Version, as the publisher.
866
 
867
       D. Preserve all the copyright notices of the Document.
868
 
869
       E. Add an appropriate copyright notice for your modifications
870
          adjacent to the other copyright notices.
871
 
872
       F. Include, immediately after the copyright notices, a license
873
          notice giving the public permission to use the Modified
874
          Version under the terms of this License, in the form shown in
875
          the Addendum below.
876
 
877
       G. Preserve in that license notice the full lists of Invariant
878
          Sections and required Cover Texts given in the Document's
879
          license notice.
880
 
881
       H. Include an unaltered copy of this License.
882
 
883
       I. Preserve the section Entitled "History", Preserve its Title,
884
          and add to it an item stating at least the title, year, new
885
          authors, and publisher of the Modified Version as given on
886
          the Title Page.  If there is no section Entitled "History" in
887
          the Document, create one stating the title, year, authors,
888
          and publisher of the Document as given on its Title Page,
889
          then add an item describing the Modified Version as stated in
890
          the previous sentence.
891
 
892
       J. Preserve the network location, if any, given in the Document
893
          for public access to a Transparent copy of the Document, and
894
          likewise the network locations given in the Document for
895
          previous versions it was based on.  These may be placed in
896
          the "History" section.  You may omit a network location for a
897
          work that was published at least four years before the
898
          Document itself, or if the original publisher of the version
899
          it refers to gives permission.
900
 
901
       K. For any section Entitled "Acknowledgements" or "Dedications",
902
          Preserve the Title of the section, and preserve in the
903
          section all the substance and tone of each of the contributor
904
          acknowledgements and/or dedications given therein.
905
 
906
       L. Preserve all the Invariant Sections of the Document,
907
          unaltered in their text and in their titles.  Section numbers
908
          or the equivalent are not considered part of the section
909
          titles.
910
 
911
       M. Delete any section Entitled "Endorsements".  Such a section
912
          may not be included in the Modified Version.
913
 
914
       N. Do not retitle any existing section to be Entitled
915
          "Endorsements" or to conflict in title with any Invariant
916
          Section.
917
 
918
       O. Preserve any Warranty Disclaimers.
919
 
920
     If the Modified Version includes new front-matter sections or
921
     appendices that qualify as Secondary Sections and contain no
922
     material copied from the Document, you may at your option
923
     designate some or all of these sections as invariant.  To do this,
924
     add their titles to the list of Invariant Sections in the Modified
925
     Version's license notice.  These titles must be distinct from any
926
     other section titles.
927
 
928
     You may add a section Entitled "Endorsements", provided it contains
929
     nothing but endorsements of your Modified Version by various
930
     parties--for example, statements of peer review or that the text
931
     has been approved by an organization as the authoritative
932
     definition of a standard.
933
 
934
     You may add a passage of up to five words as a Front-Cover Text,
935
     and a passage of up to 25 words as a Back-Cover Text, to the end
936
     of the list of Cover Texts in the Modified Version.  Only one
937
     passage of Front-Cover Text and one of Back-Cover Text may be
938
     added by (or through arrangements made by) any one entity.  If the
939
     Document already includes a cover text for the same cover,
940
     previously added by you or by arrangement made by the same entity
941
     you are acting on behalf of, you may not add another; but you may
942
     replace the old one, on explicit permission from the previous
943
     publisher that added the old one.
944
 
945
     The author(s) and publisher(s) of the Document do not by this
946
     License give permission to use their names for publicity for or to
947
     assert or imply endorsement of any Modified Version.
948
 
949
  5. COMBINING DOCUMENTS
950
 
951
     You may combine the Document with other documents released under
952
     this License, under the terms defined in section 4 above for
953
     modified versions, provided that you include in the combination
954
     all of the Invariant Sections of all of the original documents,
955
     unmodified, and list them all as Invariant Sections of your
956
     combined work in its license notice, and that you preserve all
957
     their Warranty Disclaimers.
958
 
959
     The combined work need only contain one copy of this License, and
960
     multiple identical Invariant Sections may be replaced with a single
961
     copy.  If there are multiple Invariant Sections with the same name
962
     but different contents, make the title of each such section unique
963
     by adding at the end of it, in parentheses, the name of the
964
     original author or publisher of that section if known, or else a
965
     unique number.  Make the same adjustment to the section titles in
966
     the list of Invariant Sections in the license notice of the
967
     combined work.
968
 
969
     In the combination, you must combine any sections Entitled
970
     "History" in the various original documents, forming one section
971
     Entitled "History"; likewise combine any sections Entitled
972
     "Acknowledgements", and any sections Entitled "Dedications".  You
973
     must delete all sections Entitled "Endorsements."
974
 
975
  6. COLLECTIONS OF DOCUMENTS
976
 
977
     You may make a collection consisting of the Document and other
978
     documents released under this License, and replace the individual
979
     copies of this License in the various documents with a single copy
980
     that is included in the collection, provided that you follow the
981
     rules of this License for verbatim copying of each of the
982
     documents in all other respects.
983
 
984
     You may extract a single document from such a collection, and
985
     distribute it individually under this License, provided you insert
986
     a copy of this License into the extracted document, and follow
987
     this License in all other respects regarding verbatim copying of
988
     that document.
989
 
990
  7. AGGREGATION WITH INDEPENDENT WORKS
991
 
992
     A compilation of the Document or its derivatives with other
993
     separate and independent documents or works, in or on a volume of
994
     a storage or distribution medium, is called an "aggregate" if the
995
     copyright resulting from the compilation is not used to limit the
996
     legal rights of the compilation's users beyond what the individual
997
     works permit.  When the Document is included in an aggregate, this
998
     License does not apply to the other works in the aggregate which
999
     are not themselves derivative works of the Document.
1000
 
1001
     If the Cover Text requirement of section 3 is applicable to these
1002
     copies of the Document, then if the Document is less than one half
1003
     of the entire aggregate, the Document's Cover Texts may be placed
1004
     on covers that bracket the Document within the aggregate, or the
1005
     electronic equivalent of covers if the Document is in electronic
1006
     form.  Otherwise they must appear on printed covers that bracket
1007
     the whole aggregate.
1008
 
1009
  8. TRANSLATION
1010
 
1011
     Translation is considered a kind of modification, so you may
1012
     distribute translations of the Document under the terms of section
1013
     4.  Replacing Invariant Sections with translations requires special
1014
     permission from their copyright holders, but you may include
1015
     translations of some or all Invariant Sections in addition to the
1016
     original versions of these Invariant Sections.  You may include a
1017
     translation of this License, and all the license notices in the
1018
     Document, and any Warranty Disclaimers, provided that you also
1019
     include the original English version of this License and the
1020
     original versions of those notices and disclaimers.  In case of a
1021
     disagreement between the translation and the original version of
1022
     this License or a notice or disclaimer, the original version will
1023
     prevail.
1024
 
1025
     If a section in the Document is Entitled "Acknowledgements",
1026
     "Dedications", or "History", the requirement (section 4) to
1027
     Preserve its Title (section 1) will typically require changing the
1028
     actual title.
1029
 
1030
  9. TERMINATION
1031
 
1032
     You may not copy, modify, sublicense, or distribute the Document
1033
     except as expressly provided for under this License.  Any other
1034
     attempt to copy, modify, sublicense or distribute the Document is
1035
     void, and will automatically terminate your rights under this
1036
     License.  However, parties who have received copies, or rights,
1037
     from you under this License will not have their licenses
1038
     terminated so long as such parties remain in full compliance.
1039
 
1040
 10. FUTURE REVISIONS OF THIS LICENSE
1041
 
1042
     The Free Software Foundation may publish new, revised versions of
1043
     the GNU Free Documentation License from time to time.  Such new
1044
     versions will be similar in spirit to the present version, but may
1045
     differ in detail to address new problems or concerns.  See
1046
     `http://www.gnu.org/copyleft/'.
1047
 
1048
     Each version of the License is given a distinguishing version
1049
     number.  If the Document specifies that a particular numbered
1050
     version of this License "or any later version" applies to it, you
1051
     have the option of following the terms and conditions either of
1052
     that specified version or of any later version that has been
1053
     published (not as a draft) by the Free Software Foundation.  If
1054
     the Document does not specify a version number of this License,
1055
     you may choose any version ever published (not as a draft) by the
1056
     Free Software Foundation.
1057
 
1058
14.1 ADDENDUM: How to use this License for your documents
1059
=========================================================
1060
 
1061
To use this License in a document you have written, include a copy of
1062
the License in the document and put the following copyright and license
1063
notices just after the title page:
1064
 
1065
       Copyright (C)  YEAR  YOUR NAME.
1066
       Permission is granted to copy, distribute and/or modify this document
1067
       under the terms of the GNU Free Documentation License, Version 1.2
1068
       or any later version published by the Free Software Foundation;
1069
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
1070
       Texts.  A copy of the license is included in the section entitled ``GNU
1071
       Free Documentation License''.
1072
 
1073
   If you have Invariant Sections, Front-Cover Texts and Back-Cover
1074
Texts, replace the "with...Texts." line with this:
1075
 
1076
         with the Invariant Sections being LIST THEIR TITLES, with
1077
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
1078
         being LIST.
1079
 
1080
   If you have Invariant Sections without Cover Texts, or some other
1081
combination of the three, merge those two alternatives to suit the
1082
situation.
1083
 
1084
   If your document contains nontrivial examples of program code, we
1085
recommend releasing these examples in parallel under your choice of
1086
free software license, such as the GNU General Public License, to
1087
permit their use in free software.
1088
 
1089
 
1090

1091
Tag Table:
1092
Node: Top763
1093
Node: Annotations Overview1862
1094
Node: Limitations3661
1095
Node: Migrating to GDB/MI6246
1096
Node: Server Prefix6629
1097
Node: Value Annotations7275
1098
Node: Frame Annotations10445
1099
Node: Displays14344
1100
Node: Prompting15375
1101
Node: Errors16878
1102
Node: Breakpoint Info17768
1103
Node: Invalidation18993
1104
Node: Annotations for Running19472
1105
Node: Source Annotations20985
1106
Node: GNU Free Documentation License21942
1107

1108
End Tag Table

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.