From fe715d06b665f998c2de1169a1578dbf32a57e96 Mon Sep 17 00:00:00 2001 From: Roland Pesch Date: Wed, 10 Feb 1993 02:28:16 +0000 Subject: misc updates --- gdb/doc/ChangeLog | 4 ++ gdb/doc/gdb-config.texi | 3 + gdb/doc/gdb.texinfo | 175 ++++++++++++++++++++++++++++++++++-------------- gdb/doc/gdbinv-s.texi | 81 ++++++++++++++++++---- gdb/doc/h8-config.texi | 1 + 5 files changed, 201 insertions(+), 63 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 8772cf4..2c315b0 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,7 @@ +Tue Feb 9 18:26:21 1993 Roland H. Pesch (pesch@fowanton.cygnus.com) + + * gdb.texinfo, gdbinv-s.texi: misc updates + Sat Feb 6 10:25:47 1993 John Gilmore (gnu@cygnus.com) * gdbint.texinfo: Brief documentation for longjmp support, diff --git a/gdb/doc/gdb-config.texi b/gdb/doc/gdb-config.texi index 367e37b..fab8a62 100644 --- a/gdb/doc/gdb-config.texi +++ b/gdb/doc/gdb-config.texi @@ -59,6 +59,9 @@ @c Specifically for host machine running DOS? @clear DOSHOST @c +@c Talk about CPU simulator targets? +@set SIMS +@c @c Is manual stand-alone, or part of an agglomeration, with overall GPL? @clear AGGLOMERATION @c diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 56745bc..b7409cd 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -18,8 +18,8 @@ @c %**end of header @iftex -@c smallbook -@c cropmarks +@c @smallbook +@c @cropmarks @end iftex @c Include the readline documentation in the TeX output, @@ -44,6 +44,9 @@ @finalout @syncodeindex ky cp +@c readline appendices use @vindex +@syncodeindex vr cp + @c ===> NOTE! <== @c Determine the edition number in *three* places by hand: @c 1. First ifinfo section 2. title page 3. top node @@ -1351,6 +1354,7 @@ in sequential order. The order makes a difference when the * i960-Nindy Remote:: @value{GDBN} with a remote i960 (Nindy) @end ifset @ifset AMDxxixK +* UDI29K Remote:: @value{GDBN} and the UDI protocol for AMD29K * EB29K Remote:: @value{GDBN} with a remote EB29K @end ifset @ifset VXWORKS @@ -1362,8 +1366,8 @@ in sequential order. The order makes a difference when the @ifset Hviii * Hitachi H8/300 Remote:: @value{GDBN} and the Hitachi H8/300 @end ifset -@ifset ZviiiK -* Z8000 Simulator:: @value{GDBN} and its Zilog Z8000 Simulator +@ifset SIMS +* Simulator:: Simulated CPU target @end ifset @end ifclear * File Options:: Choosing files @@ -1395,6 +1399,7 @@ in sequential order. The order makes a difference when the @ifclear ZviiiK @menu * Hitachi H8/300 Remote:: @value{GDBN} and the Hitachi H8/300 +* Simulator:: Simulated CPU target * File Options:: Choosing files * Mode Options:: Choosing modes @end menu @@ -1651,12 +1656,12 @@ show you the alternatives available, if there is more than one possibility). @node Command Syntax @section Command syntax -A @value{GDBN} command is a single line of input. There is no limit on how long -it can be. It starts with a command name, which is followed by arguments -whose meaning depends on the command name. For example, the command -@code{step} accepts an argument which is the number of times to step, -as in @samp{step 5}. You can also use the @code{step} command with -no arguments. Some command names do not allow any arguments. +A @value{GDBN} command is a single line of input. There is no limit on +how long it can be. It starts with a command name, which is followed by +arguments whose meaning depends on the command name. For example, the +command @code{step} accepts an argument which is the number of times to +step, as in @samp{step 5}. You can also use the @code{step} command +with no arguments. Some command names do not allow any arguments. @cindex abbreviation @value{GDBN} command names may always be truncated if that abbreviation is @@ -1687,8 +1692,9 @@ repetition after any command that generates this sort of display. @kindex # @cindex comment -A line of input starting with @kbd{#} is a comment; it does nothing. -This is useful mainly in command files (@pxref{Command Files,,Command files}). +Any text from a @kbd{#} to the end of the line is a comment; it does +nothing. This is useful mainly in command files (@pxref{Command +Files,,Command files}). @node Completion @section Command completion @@ -2529,6 +2535,10 @@ watchpoints}), but aside from that, you can manage a watchpoint like any other breakpoint: you enable, disable, and delete both breakpoints and watchpoints using the same commands. +You can arrange to have values from your program displayed automatically +whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display, +,Automatic display}. + @cindex breakpoint numbers @cindex numbers for breakpoints @value{GDBN} assigns a number to each breakpoint or watchpoint when you @@ -3096,16 +3106,21 @@ disabled within a @var{command-list}. You can use breakpoint commands to start your program up again. Simply use the @code{continue} command, or @code{step}, or any other command -that resumes execution. Subsequent commands in the command list are -ignored. +that resumes execution. + +Any other commands in the command list, after a command that resumes +execution, are ignored. This is because any time you resume execution +(even with a simple @code{next} or @code{step}), you may encounter +another breakpoint---which could have its own command list, leading to +ambiguities about which list to execute. @kindex silent -If the first command specified is @code{silent}, the usual message -about stopping at a breakpoint is not printed. This may be desirable -for breakpoints that are to print a specific message and then continue. -If none of the remaining commands print anything, you will see no sign -that the breakpoint was reached. @code{silent} is meaningful only at -the beginning of a breakpoint command list. +If the first command you specify in a command list is @code{silent}, the +usual message about stopping at a breakpoint is not printed. This may +be desirable for breakpoints that are to print a specific message and +then continue. If none of the remaining commands print anything, you +will see no sign that the breakpoint was reached. @code{silent} is +meaningful only at the beginning of a breakpoint command list. The commands @code{echo} and @code{output} that allow you to print precisely controlled output are often useful in silent breakpoints. @@ -4244,7 +4259,7 @@ command rather than @code{print}. @xref{Symbols, ,Examining the Symbol Table}. @cindex expressions @code{print} and many other @value{GDBN} commands accept an expression and compute its value. Any kind of constant, variable or operator defined -by the programming language you are using is legal in an expression in +by the programming language you are using is valid in an expression in @value{GDBN}. This includes conditional expressions, function calls, casts and string constants. It unfortunately does not include symbols defined by preprocessor @code{#define} commands. @@ -4277,6 +4292,10 @@ languages: function where it is defined. @xref{Variables, ,Program variables}. @item @{@var{type}@} @var{addr} +@cindex @{@var{type}@} +@cindex type casting memory +@cindex memory, viewing as typed object +@cindex casts, to view memory Refers to an object of type @var{type} stored at address @var{addr} in memory. @var{addr} may be any expression whose value is an integer or pointer (but parentheses are required around binary operators, just as in @@ -4378,14 +4397,15 @@ same type in memory; a section of an array, or an array of dynamically determined size for which only a pointer exists in the program. -This can be done by constructing an @dfn{artificial array} with the -binary operator @samp{@@}. The left operand of @samp{@@} should be -the first element of the desired array, as an individual object. -The right operand should be the desired length of the array. The result is -an array value whose elements are all of the type of the left argument. -The first element is actually the left argument; the second element -comes from bytes of memory immediately following those that hold the -first element, and so on. Here is an example. If a program says +You can do this by referring to a contiguous span of memory as an +@dfn{artificial array}, using the binary operator @samp{@@}. The left +operand of @samp{@@} should be the first element of the desired array, +as an individual object. The right operand should be the desired length +of the array. The result is an array value whose elements are all of +the type of the left argument. The first element is actually the left +argument; the second element comes from bytes of memory immediately +following those that hold the first element, and so on. Here is an +example. If a program says @example int *array = (int *) malloc (len * sizeof (int)); @@ -4455,6 +4475,9 @@ Print as integer in octal. @item t Print as integer in binary. The letter @samp{t} stands for ``two''. +@footnote{@samp{b} cannot be used because these format letters are also +used with the @code{x} command, where @samp{b} stands for ``byte''; +@pxref{Memory,,Examining memory}.} @item a Print as an address, both absolute in hex and as an offset from the @@ -4732,6 +4755,11 @@ this is the same stack frame displayed with @code{set print address off}: @end group @end example +You can use @samp{set print address off} to eliminate all machine +dependent displays from the @value{GDBN} interface. For example, with +@code{print address off}, you should get the same text for backtraces on +all machines---whether or not they involve pointer arguments. + @item show print address @kindex show print address Show whether or not addresses are to be printed. @@ -4742,7 +4770,7 @@ Show whether or not addresses are to be printed. @value{GDBN} will pretty print arrays. This format is more convenient to read, but uses more space. The default is off. -@item set print array off. +@item set print array off Return to compressed format for arrays. @item show print array @@ -4865,9 +4893,9 @@ These settings are of interest when debugging C++ programs: @item set print demangle @itemx set print demangle on @kindex set print demangle -Print C++ names in their source form rather than in the mangled form -in which they are passed to the assembler and linker for type-safe linkage. -The default is on. +Print C++ names in their source form rather than in the encoded +(``mangled'') form passed to the assembler and linker for type-safe +linkage. The default is @samp{on}. @item show print demangle @kindex show print demangle @@ -4885,6 +4913,34 @@ The default is off. Show whether C++ names in assembly listings will be printed in mangled or demangled form. +@item set demangle-style @var{style} +@kindex set demangle-style +@cindex C++ symbol decoding style +@cindex symbol decoding style, C++ +Choose among several encoding schemes used by different compilers to +represent C++ names. The choices for @var{style} are currently: + +@table @code +@item auto +Allow @value{GDBN} to choose a decoding style by inspecting your program. + +@item gnu +Decode based on the GNU C++ compiler (@code{g++}) encoding algorithm. + +@item lucid +Decode based on the Lucid C++ compiler (@code{lcc}) encoding algorithm. + +@item cfront +Decode using the algorithm in the @cite{C++ Annotated Reference Manual}. +@strong{Warning:} despite the name, this setting alone is not sufficient +to allow debugging @code{cfront}-generated executables. @value{GDBN} +would require further enhancement to permit that. +@end table + +@item show demangle-style +@kindex show demangle-style +Display the encoding style currently in use for decoding C++ symbols. + @item set print object @itemx set print object on @kindex set print object @@ -5782,7 +5838,14 @@ String constants are a sequence of character constants surrounded by double quotes (@code{"}). @item -Pointer constants are an integral value. +Pointer constants are an integral value. You can also write pointers +to constants using the C operator @samp{&}. + +@item +Array constants are comma-separated lists surrounded by braces @samp{@{} +and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of +integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array, +and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers. @end itemize @ifclear CONLY @@ -7365,10 +7428,10 @@ Here are some common targets (available, or not, depending on the GDB configuration): @table @code -@item target exec @var{prog} +@item target exec @var{program} @kindex target exec -An executable file. @samp{target exec @var{prog}} is the same as -@samp{exec-file @var{prog}}. +An executable file. @samp{target exec @var{program}} is the same as +@samp{exec-file @var{program}}. @item target core @var{filename} @kindex target core @@ -7383,7 +7446,19 @@ specifies what serial device to use for the connection (e.g. @file{/dev/ttya}). @xref{Remote, ,Remote debugging}. @end ifset +@ifset SIMS +@item target sim +@kindex target sim +CPU simulator. @xref{Simulator,,Simulated CPU Target}. +@end ifset + @ifset AMDxxixK +@item target udi @var{keyword} +@kindex target udi +Remote AMD29K target, using the AMD UDI protocol. The @var{keyword} +argument specifies which 29K board or simulator to use. @xref{UDI29K +Remote,,@value{GDBN} and the UDI protocol for AMD29K}. + @item target amd-eb @var{dev} @var{speed} @var{PROG} @kindex target amd-eb @cindex AMD EB29K @@ -7469,6 +7544,7 @@ configuration of GDB; use @code{help targets} to list them. * i960-Nindy Remote:: @value{GDBN} with a remote i960 (Nindy) @end ifset @ifset AMDxxixK +* UDI29K Remote:: @value{GDBN} and the UDI protocol for AMD29K * EB29K Remote:: @value{GDBN} with a remote EB29K @end ifset @ifset VXWORKS @@ -7480,8 +7556,8 @@ configuration of GDB; use @code{help targets} to list them. @ifset Hviii * Hitachi H8/300 Remote:: @value{GDBN} and the Hitachi H8/300 @end ifset -@ifset ZviiiK -* Z8000 Simulator:: @value{GDBN} and its Zilog Z8000 Simulator +@ifset SIMS +* Simulator:: Simulated CPU target @end ifset @end menu @end ignore @@ -7493,11 +7569,12 @@ configuration of GDB; use @code{help targets} to list them. @menu * Remote Serial:: @value{GDBN} remote serial protocol * i960-Nindy Remote:: @value{GDBN} with a remote i960 (Nindy) +* UDI29K Remote:: @value{GDBN} and the UDI protocol for AMD29K * EB29K Remote:: @value{GDBN} with a remote EB29K * VxWorks Remote:: @value{GDBN} and VxWorks * ST2000 Remote:: @value{GDBN} with a Tandem ST2000 * Hitachi H8/300 Remote:: @value{GDBN} and the Hitachi H8/300 -* Z8000 Simulator:: @value{GDBN} and its Zilog Z8000 Simulator +* Simulator:: Simulated CPUs @end menu @include gdbinv-s.texi @@ -8098,7 +8175,7 @@ stop. Each time @value{GDBN} displays a stack frame, Emacs automatically finds the source file for that frame and puts an arrow (@samp{=>}) at the left margin of the current line. Emacs uses a separate buffer for -source display, and splits the window to show both your @value{GDBN} session +source display, and splits the screen to show both your @value{GDBN} session and the source. Explicit @value{GDBN} @code{list} or search commands still produce output as @@ -8608,7 +8685,7 @@ unset &&\rm(No longer an alias for delete)\cr @ifclear PRECONFIGURED @node Formatting Documentation -@appendix Formatting the Documentation +@appendix Formatting Documentation @cindex GDB reference card @cindex reference card @@ -8662,17 +8739,17 @@ cd gdb make gdb.info @end example -If you want to typeset and print copies of this manual, you need -@TeX{}, a printing program such as @code{lpr}, and @file{texinfo.tex}, -the Texinfo definitions file. +If you want to typeset and print copies of this manual, you need @TeX{}, +a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the +Texinfo definitions file. @TeX{} is a typesetting program; it does not print files directly, but produces output files called @sc{dvi} files. To print a typeset document, you need a program to print @sc{dvi} files. If your system has @TeX{} installed, chances are it has such a program. The precise command to use depends on your system; @kbd{lpr -d} is common; another -is @kbd{dvips}. The @sc{dvi} print command may require a file name -without any extension or a @samp{.dvi} extension. +(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may +require a file name without any extension or a @samp{.dvi} extension. @TeX{} also requires a macro definitions file called @file{texinfo.tex}. This file tells @TeX{} how to typeset a document @@ -8856,7 +8933,7 @@ When you run @code{make} to build a program or library, you must run it in a configured directory---whatever directory you were in when you called @code{configure} (or one of its subdirectories). -The @code{Makefile} generated by @code{configure} for each source +The @code{Makefile} that @code{configure} generates in each source directory also runs recursively. If you type @code{make} in a source directory such as @file{gdb-@value{GDBVN}} (or in a separate configured directory configured with @samp{--srcdir=@var{path}/gdb-@value{GDBVN}}), you @@ -8880,7 +8957,7 @@ of information in the following pattern: @end example For example, you can use the alias @code{sun4} as a @var{host} argument -or in a @code{--target=@var{target}} option, but the equivalent full name +or in a @code{--target=@var{target}} option. The equivalent full name is @samp{sparc-sun-sunos4}. The @code{configure} script accompanying GDB does not provide diff --git a/gdb/doc/gdbinv-s.texi b/gdb/doc/gdbinv-s.texi index 8403b76..f345d01 100644 --- a/gdb/doc/gdbinv-s.texi +++ b/gdb/doc/gdbinv-s.texi @@ -443,6 +443,29 @@ a break is detected. @end ifset @ifset AMDxxixK +@node UDI29K Remote +@subsection @value{GDBN} and the UDI protocol for AMD29K + +@cindex UDI +@cindex AMD29K via UDI +@value{GDBN} supports AMD's UDI (``Universal Debugger Interface'') +protocol for debugging the 29k processor family. To use this +configuration with AMD targets running the MiniMON monitor, you need the +program @code{MONTIP}, available from AMD at no charge. You can also +use @value{GDBN} with the UDI conformant 29k simulator program +@code{ISSTIP}, also available from AMD. + +@table @code +@item target udi @var{keyword} +@kindex udi +Select the UDI interface to a remote 29K board or simulator, where +@var{keyword} is an entry in the AMD configuration file @file{udi_soc}. +This file contains keyword entries which specify parameters used to +connect to 29k targets. If the @file{udi_soc} file is not in your +working directory, you must set the environment variable @samp{UDICONF} +to its pathname. +@end table + @node EB29K Remote @subsection @value{GDBN} with a remote EB29K @@ -508,7 +531,7 @@ tip -9600 /dev/ttya @end example @noindent -Your system may define a different name where our example uses +Your system may require a different name where we show @file{/dev/ttya} as the argument to @code{tip}. The communications parameters, including which port to use, are associated with the @code{tip} argument in the ``remote'' descriptions file---normally the @@ -941,33 +964,63 @@ In either case, @value{GDBN} will see the effect of a @sc{reset} on the H8/300 board as a ``normal exit'' of your program. @end ifset -@ifset ZviiiK -@node Z8000 Simulator -@subsection @value{GDBN} and its Zilog Z8000 simulator +@ifset SIMS +@node Simulator +@subsection Simulated CPU target +@ifset GENERIC +@cindex simulator +@cindex simulator, Z8000 +@cindex simulator, H8/300 +@cindex Z8000 simulator +@cindex H8/300 simulator +@cindex CPU simulator +For some configurations, @value{GDBN} includes a CPU simulator that you +can use instead of a hardware CPU to debug your programs. Currently, +a simulator is available when @value{GDBN} is configured to debug Zilog +Z8000 or Hitachi H8/300 targets. +@end ifset + +@ifclear GENERIC +@ifset Hviii +@cindex simulator, H8/300 +@cindex Hitachi H8/300 simulator +When configured for debugging Hitachi H8/300 targets, @value{GDBN} includes +an H8/300 CPU simulator. +@end ifset + +@ifset ZviiiK @cindex simulator, Z8000 @cindex Zilog Z8000 simulator When configured for debugging Zilog Z8000 targets, @value{GDBN} includes a Z8000 simulator. +@end ifset +@end ifclear + +@ifset ZviiiK +For the Z8000 family, @samp{target sim} simulates either the Z8002 (the +unsegmented variant of the Z8000 architecture) or the Z8001 (the +segmented variant). The simulator recognizes which architecture is +appropriate by inspecting the object code. +@end ifset @table @code @item target sim @kindex sim @kindex target sim -This debugging target is a machine simulator; when @value{GDBN} is -configured for the Z8000 family, @samp{target sim} simulates either the -Z8002 (the unsegmented variant of the Z8000 architecture) or the Z8001 -(the segmented variant). The simulator recognizes which architecture is -appropriate by inspecting the object code. +Debug programs on a simulated CPU +@ifset GENERIC +(which CPU depends on the @value{GDBN} configuration) +@end ifset @end table @noindent -After specifying this target, you can debug Z8000 programs in the same -style as programs for your host computer; use the @code{file} command to -load a new program image, the @code{run} command to run your program, -and so on. +After specifying this target, you can debug programs for the simulated +CPU in the same style as programs for your host computer; use the +@code{file} command to load a new program image, the @code{run} command +to run your program, and so on. -As well as making available all the usual Z8000 registers (see +As well as making available all the usual machine registers (see @code{info reg}), this debugging target provides three additional items of information as specially named registers: diff --git a/gdb/doc/h8-config.texi b/gdb/doc/h8-config.texi index 5164cb4..05728b0 100644 --- a/gdb/doc/h8-config.texi +++ b/gdb/doc/h8-config.texi @@ -4,6 +4,7 @@ @set BARETARGET @set CONLY @set DOSHOST +@set SIMS @set AGGLOMERATION @clear SERIAL @clear VXWORKS -- cgit v1.1