with @code{void} returned values. If the result is not void, it
is printed and saved in the value history.
-For the A29K, a user-controlled variable @code{call_scratch_address},
-specifies the location of a scratch area to be used when @value{GDBN}
-calls a function in the target. This is necessary because the usual
-method of putting the scratch area on the stack does not work in systems
-that have separate instruction and data spaces.
+@c OBSOLETE For the A29K, a user-controlled variable @code{call_scratch_address},
+@c OBSOLETE specifies the location of a scratch area to be used when @value{GDBN}
+@c OBSOLETE calls a function in the target. This is necessary because the usual
+@c OBSOLETE method of putting the scratch area on the stack does not work in systems
+@c OBSOLETE that have separate instruction and data spaces.
@node Patching
@section Patching programs
This section goes into details specific to particular embedded
configurations.
+
+@c OBSOLETE * A29K Embedded:: AMD A29K Embedded
@menu
-* A29K Embedded:: AMD A29K Embedded
* ARM:: ARM
* H8/300:: Hitachi H8/300
* H8/500:: Hitachi H8/500
* Z8000:: Zilog Z8000
@end menu
-@node A29K Embedded
-@subsection AMD A29K Embedded
-
-@menu
-* A29K UDI::
-* A29K EB29K::
-* Comms (EB29K):: Communications setup
-* gdb-EB29K:: EB29K cross-debugging
-* Remote Log:: Remote log
-@end menu
-
-@table @code
-
-@kindex target adapt
-@item target adapt @var{dev}
-Adapt monitor for A29K.
-
-@kindex target amd-eb
-@item target amd-eb @var{dev} @var{speed} @var{PROG}
-@cindex AMD EB29K
-Remote PC-resident AMD EB29K board, attached over serial lines.
-@var{dev} is the serial device, as for @code{target remote};
-@var{speed} allows you to specify the linespeed; and @var{PROG} is the
-name of the program to be debugged, as it appears to DOS on the PC.
-@xref{A29K EB29K, ,EBMON protocol for AMD29K}.
-
-@end table
-
-@node A29K UDI
-@subsubsection A29K UDI
-
-@cindex UDI
-@cindex AMD29K via UDI
-
-@value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
-protocol for debugging the a29k 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 a29k simulator program
-@code{ISSTIP}, also available from AMD.
-
-@table @code
-@item target udi @var{keyword}
-@kindex udi
-Select the UDI interface to a remote a29k 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 a29k 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 A29K EB29K
-@subsubsection EBMON protocol for AMD29K
-
-@cindex EB29K board
-@cindex running 29K programs
-
-AMD distributes a 29K development board meant to fit in a PC, together
-with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
-term, this development system is called the ``EB29K''. To use
-@value{GDBN} from a Unix system to run programs on the EB29K board, you
-must first connect a serial cable between the PC (which hosts the EB29K
-board) and a serial port on the Unix system. In the following, we
-assume you've hooked the cable between the PC's @file{COM1} port and
-@file{/dev/ttya} on the Unix system.
-
-@node Comms (EB29K)
-@subsubsection Communications setup
-
-The next step is to set up the PC's port, by doing something like this
-in DOS on the PC:
-
-@example
-C:\> MODE com1:9600,n,8,1,none
-@end example
-
-@noindent
-This example---run on an MS DOS 4.0 system---sets the PC port to 9600
-bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
-you must match the communications parameters when establishing the Unix
-end of the connection as well.
-@c FIXME: Who knows what this "no retry action" crud from the DOS manual may
-@c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
-@c
-@c It's optional, but it's unwise to omit it: who knows what is the
-@c default value set when the DOS machines boots? "No retry" means that
-@c the DOS serial device driver won't retry the operation if it fails;
-@c I understand that this is needed because the GDB serial protocol
-@c handles any errors and retransmissions itself. ---Eli Zaretskii, 3sep99
-
-To give control of the PC to the Unix side of the serial line, type
-the following at the DOS console:
-
-@example
-C:\> CTTY com1
-@end example
-
-@noindent
-(Later, if you wish to return control to the DOS console, you can use
-the command @code{CTTY con}---but you must send it over the device that
-had control, in our example over the @file{COM1} serial line.)
-
-From the Unix host, use a communications program such as @code{tip} or
-@code{cu} to communicate with the PC; for example,
-
-@example
-cu -s 9600 -l /dev/ttya
-@end example
-
-@noindent
-The @code{cu} options shown specify, respectively, the linespeed and the
-serial port to use. If you use @code{tip} instead, your command line
-may look something like the following:
-
-@example
-tip -9600 /dev/ttya
-@end example
-
-@noindent
-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
-system table @file{/etc/remote}.
-@c FIXME: What if anything needs doing to match the "n,8,1,none" part of
-@c the DOS side's comms setup? cu can support -o (odd
-@c parity), -e (even parity)---apparently no settings for no parity or
-@c for character size. Taken from stty maybe...? John points out tip
-@c can set these as internal variables, eg ~s parity=none; man stty
-@c suggests that it *might* work to stty these options with stdin or
-@c stdout redirected... ---doc@cygnus.com, 25feb91
-@c
-@c There's nothing to be done for the "none" part of the DOS MODE
-@c command. The rest of the parameters should be matched by the
-@c baudrate, bits, and parity used by the Unix side. ---Eli Zaretskii, 3Sep99
-
-@kindex EBMON
-Using the @code{tip} or @code{cu} connection, change the DOS working
-directory to the directory containing a copy of your 29K program, then
-start the PC program @code{EBMON} (an EB29K control program supplied
-with your board by AMD). You should see an initial display from
-@code{EBMON} similar to the one that follows, ending with the
-@code{EBMON} prompt @samp{#}---
-
-@example
-C:\> G:
-
-G:\> CD \usr\joe\work29k
-
-G:\USR\JOE\WORK29K> EBMON
-Am29000 PC Coprocessor Board Monitor, version 3.0-18
-Copyright 1990 Advanced Micro Devices, Inc.
-Written by Gibbons and Associates, Inc.
-
-Enter '?' or 'H' for help
-
-PC Coprocessor Type = EB29K
-I/O Base = 0x208
-Memory Base = 0xd0000
-
-Data Memory Size = 2048KB
-Available I-RAM Range = 0x8000 to 0x1fffff
-Available D-RAM Range = 0x80002000 to 0x801fffff
-
-PageSize = 0x400
-Register Stack Size = 0x800
-Memory Stack Size = 0x1800
-
-CPU PRL = 0x3
-Am29027 Available = No
-Byte Write Available = Yes
-
-# ~.
-@end example
-
-Then exit the @code{cu} or @code{tip} program (done in the example by
-typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps
-running, ready for @value{GDBN} to take over.
-
-For this example, we've assumed what is probably the most convenient
-way to make sure the same 29K program is on both the PC and the Unix
-system: a PC/NFS connection that establishes ``drive @file{G:}'' on the
-PC as a file system on the Unix host. If you do not have PC/NFS or
-something similar connecting the two systems, you must arrange some
-other way---perhaps floppy-disk transfer---of getting the 29K program
-from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
-serial line.
-
-@node gdb-EB29K
-@subsubsection EB29K cross-debugging
-
-Finally, @code{cd} to the directory containing an image of your 29K
-program on the Unix system, and start @value{GDBN}---specifying as argument the
-name of your 29K program:
-
-@example
-cd /usr/joe/work29k
-@value{GDBP} myfoo
-@end example
-
-@need 500
-Now you can use the @code{target} command:
-
-@example
-target amd-eb /dev/ttya 9600 MYFOO
-@c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
-@c emphasize that this is the name as seen by DOS (since I think DOS is
-@c single-minded about case of letters). ---doc@cygnus.com, 25feb91
-@end example
-
-@noindent
-In this example, we've assumed your program is in a file called
-@file{myfoo}. Note that the filename given as the last argument to
-@code{target amd-eb} should be the name of the program as it appears to DOS.
-In our example this is simply @code{MYFOO}, but in general it can include
-a DOS path, and depending on your transfer mechanism may not resemble
-the name on the Unix side.
-
-At this point, you can set any breakpoints you wish; when you are ready
-to see your program run on the 29K board, use the @value{GDBN} command
-@code{run}.
-
-To stop debugging the remote program, use the @value{GDBN} @code{detach}
-command.
-
-To return control of the PC to its console, use @code{tip} or @code{cu}
-once again, after your @value{GDBN} session has concluded, to attach to
-@code{EBMON}. You can then type the command @code{q} to shut down
-@code{EBMON}, returning control to the DOS command-line interpreter.
-Type @kbd{CTTY con} to return command input to the main DOS console,
-and type @kbd{~.} to leave @code{tip} or @code{cu}.
-
-@node Remote Log
-@subsubsection Remote log
-@cindex @file{eb.log}, a log file for EB29K
-@cindex log file for EB29K
-
-The @code{target amd-eb} command creates a file @file{eb.log} in the
-current working directory, to help debug problems with the connection.
-@file{eb.log} records all the output from @code{EBMON}, including echoes
-of the commands sent to it. Running @samp{tail -f} on this file in
-another window often helps to understand trouble with @code{EBMON}, or
-unexpected events on the PC side of the connection.
+@c OBSOLETE @node A29K Embedded
+@c OBSOLETE @subsection AMD A29K Embedded
+@c OBSOLETE
+@c OBSOLETE @menu
+@c OBSOLETE * A29K UDI::
+@c OBSOLETE * A29K EB29K::
+@c OBSOLETE * Comms (EB29K):: Communications setup
+@c OBSOLETE * gdb-EB29K:: EB29K cross-debugging
+@c OBSOLETE * Remote Log:: Remote log
+@c OBSOLETE @end menu
+@c OBSOLETE
+@c OBSOLETE @table @code
+@c OBSOLETE
+@c OBSOLETE @kindex target adapt
+@c OBSOLETE @item target adapt @var{dev}
+@c OBSOLETE Adapt monitor for A29K.
+@c OBSOLETE
+@c OBSOLETE @kindex target amd-eb
+@c OBSOLETE @item target amd-eb @var{dev} @var{speed} @var{PROG}
+@c OBSOLETE @cindex AMD EB29K
+@c OBSOLETE Remote PC-resident AMD EB29K board, attached over serial lines.
+@c OBSOLETE @var{dev} is the serial device, as for @code{target remote};
+@c OBSOLETE @var{speed} allows you to specify the linespeed; and @var{PROG} is the
+@c OBSOLETE name of the program to be debugged, as it appears to DOS on the PC.
+@c OBSOLETE @xref{A29K EB29K, ,EBMON protocol for AMD29K}.
+@c OBSOLETE
+@c OBSOLETE @end table
+@c OBSOLETE
+@c OBSOLETE @node A29K UDI
+@c OBSOLETE @subsubsection A29K UDI
+@c OBSOLETE
+@c OBSOLETE @cindex UDI
+@c OBSOLETE @cindex AMD29K via UDI
+@c OBSOLETE
+@c OBSOLETE @value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
+@c OBSOLETE protocol for debugging the a29k processor family. To use this
+@c OBSOLETE configuration with AMD targets running the MiniMON monitor, you need the
+@c OBSOLETE program @code{MONTIP}, available from AMD at no charge. You can also
+@c OBSOLETE use @value{GDBN} with the UDI-conformant a29k simulator program
+@c OBSOLETE @code{ISSTIP}, also available from AMD.
+@c OBSOLETE
+@c OBSOLETE @table @code
+@c OBSOLETE @item target udi @var{keyword}
+@c OBSOLETE @kindex udi
+@c OBSOLETE Select the UDI interface to a remote a29k board or simulator, where
+@c OBSOLETE @var{keyword} is an entry in the AMD configuration file @file{udi_soc}.
+@c OBSOLETE This file contains keyword entries which specify parameters used to
+@c OBSOLETE connect to a29k targets. If the @file{udi_soc} file is not in your
+@c OBSOLETE working directory, you must set the environment variable @samp{UDICONF}
+@c OBSOLETE to its pathname.
+@c OBSOLETE @end table
+@c OBSOLETE
+@c OBSOLETE @node A29K EB29K
+@c OBSOLETE @subsubsection EBMON protocol for AMD29K
+@c OBSOLETE
+@c OBSOLETE @cindex EB29K board
+@c OBSOLETE @cindex running 29K programs
+@c OBSOLETE
+@c OBSOLETE AMD distributes a 29K development board meant to fit in a PC, together
+@c OBSOLETE with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
+@c OBSOLETE term, this development system is called the ``EB29K''. To use
+@c OBSOLETE @value{GDBN} from a Unix system to run programs on the EB29K board, you
+@c OBSOLETE must first connect a serial cable between the PC (which hosts the EB29K
+@c OBSOLETE board) and a serial port on the Unix system. In the following, we
+@c OBSOLETE assume you've hooked the cable between the PC's @file{COM1} port and
+@c OBSOLETE @file{/dev/ttya} on the Unix system.
+@c OBSOLETE
+@c OBSOLETE @node Comms (EB29K)
+@c OBSOLETE @subsubsection Communications setup
+@c OBSOLETE
+@c OBSOLETE The next step is to set up the PC's port, by doing something like this
+@c OBSOLETE in DOS on the PC:
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE C:\> MODE com1:9600,n,8,1,none
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE This example---run on an MS DOS 4.0 system---sets the PC port to 9600
+@c OBSOLETE bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
+@c OBSOLETE you must match the communications parameters when establishing the Unix
+@c OBSOLETE end of the connection as well.
+@c OBSOLETE @c FIXME: Who knows what this "no retry action" crud from the DOS manual may
+@c OBSOLETE @c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91
+@c OBSOLETE @c
+@c OBSOLETE @c It's optional, but it's unwise to omit it: who knows what is the
+@c OBSOLETE @c default value set when the DOS machines boots? "No retry" means that
+@c OBSOLETE @c the DOS serial device driver won't retry the operation if it fails;
+@c OBSOLETE @c I understand that this is needed because the GDB serial protocol
+@c OBSOLETE @c handles any errors and retransmissions itself. ---Eli Zaretskii, 3sep99
+@c OBSOLETE
+@c OBSOLETE To give control of the PC to the Unix side of the serial line, type
+@c OBSOLETE the following at the DOS console:
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE C:\> CTTY com1
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE (Later, if you wish to return control to the DOS console, you can use
+@c OBSOLETE the command @code{CTTY con}---but you must send it over the device that
+@c OBSOLETE had control, in our example over the @file{COM1} serial line.)
+@c OBSOLETE
+@c OBSOLETE From the Unix host, use a communications program such as @code{tip} or
+@c OBSOLETE @code{cu} to communicate with the PC; for example,
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE cu -s 9600 -l /dev/ttya
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE The @code{cu} options shown specify, respectively, the linespeed and the
+@c OBSOLETE serial port to use. If you use @code{tip} instead, your command line
+@c OBSOLETE may look something like the following:
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE tip -9600 /dev/ttya
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE Your system may require a different name where we show
+@c OBSOLETE @file{/dev/ttya} as the argument to @code{tip}. The communications
+@c OBSOLETE parameters, including which port to use, are associated with the
+@c OBSOLETE @code{tip} argument in the ``remote'' descriptions file---normally the
+@c OBSOLETE system table @file{/etc/remote}.
+@c OBSOLETE @c FIXME: What if anything needs doing to match the "n,8,1,none" part of
+@c OBSOLETE @c the DOS side's comms setup? cu can support -o (odd
+@c OBSOLETE @c parity), -e (even parity)---apparently no settings for no parity or
+@c OBSOLETE @c for character size. Taken from stty maybe...? John points out tip
+@c OBSOLETE @c can set these as internal variables, eg ~s parity=none; man stty
+@c OBSOLETE @c suggests that it *might* work to stty these options with stdin or
+@c OBSOLETE @c stdout redirected... ---doc@cygnus.com, 25feb91
+@c OBSOLETE @c
+@c OBSOLETE @c There's nothing to be done for the "none" part of the DOS MODE
+@c OBSOLETE @c command. The rest of the parameters should be matched by the
+@c OBSOLETE @c baudrate, bits, and parity used by the Unix side. ---Eli Zaretskii, 3Sep99
+@c OBSOLETE
+@c OBSOLETE @kindex EBMON
+@c OBSOLETE Using the @code{tip} or @code{cu} connection, change the DOS working
+@c OBSOLETE directory to the directory containing a copy of your 29K program, then
+@c OBSOLETE start the PC program @code{EBMON} (an EB29K control program supplied
+@c OBSOLETE with your board by AMD). You should see an initial display from
+@c OBSOLETE @code{EBMON} similar to the one that follows, ending with the
+@c OBSOLETE @code{EBMON} prompt @samp{#}---
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE C:\> G:
+@c OBSOLETE
+@c OBSOLETE G:\> CD \usr\joe\work29k
+@c OBSOLETE
+@c OBSOLETE G:\USR\JOE\WORK29K> EBMON
+@c OBSOLETE Am29000 PC Coprocessor Board Monitor, version 3.0-18
+@c OBSOLETE Copyright 1990 Advanced Micro Devices, Inc.
+@c OBSOLETE Written by Gibbons and Associates, Inc.
+@c OBSOLETE
+@c OBSOLETE Enter '?' or 'H' for help
+@c OBSOLETE
+@c OBSOLETE PC Coprocessor Type = EB29K
+@c OBSOLETE I/O Base = 0x208
+@c OBSOLETE Memory Base = 0xd0000
+@c OBSOLETE
+@c OBSOLETE Data Memory Size = 2048KB
+@c OBSOLETE Available I-RAM Range = 0x8000 to 0x1fffff
+@c OBSOLETE Available D-RAM Range = 0x80002000 to 0x801fffff
+@c OBSOLETE
+@c OBSOLETE PageSize = 0x400
+@c OBSOLETE Register Stack Size = 0x800
+@c OBSOLETE Memory Stack Size = 0x1800
+@c OBSOLETE
+@c OBSOLETE CPU PRL = 0x3
+@c OBSOLETE Am29027 Available = No
+@c OBSOLETE Byte Write Available = Yes
+@c OBSOLETE
+@c OBSOLETE # ~.
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE Then exit the @code{cu} or @code{tip} program (done in the example by
+@c OBSOLETE typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps
+@c OBSOLETE running, ready for @value{GDBN} to take over.
+@c OBSOLETE
+@c OBSOLETE For this example, we've assumed what is probably the most convenient
+@c OBSOLETE way to make sure the same 29K program is on both the PC and the Unix
+@c OBSOLETE system: a PC/NFS connection that establishes ``drive @file{G:}'' on the
+@c OBSOLETE PC as a file system on the Unix host. If you do not have PC/NFS or
+@c OBSOLETE something similar connecting the two systems, you must arrange some
+@c OBSOLETE other way---perhaps floppy-disk transfer---of getting the 29K program
+@c OBSOLETE from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
+@c OBSOLETE serial line.
+@c OBSOLETE
+@c OBSOLETE @node gdb-EB29K
+@c OBSOLETE @subsubsection EB29K cross-debugging
+@c OBSOLETE
+@c OBSOLETE Finally, @code{cd} to the directory containing an image of your 29K
+@c OBSOLETE program on the Unix system, and start @value{GDBN}---specifying as argument the
+@c OBSOLETE name of your 29K program:
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE cd /usr/joe/work29k
+@c OBSOLETE @value{GDBP} myfoo
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @need 500
+@c OBSOLETE Now you can use the @code{target} command:
+@c OBSOLETE
+@c OBSOLETE @example
+@c OBSOLETE target amd-eb /dev/ttya 9600 MYFOO
+@c OBSOLETE @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
+@c OBSOLETE @c emphasize that this is the name as seen by DOS (since I think DOS is
+@c OBSOLETE @c single-minded about case of letters). ---doc@cygnus.com, 25feb91
+@c OBSOLETE @end example
+@c OBSOLETE
+@c OBSOLETE @noindent
+@c OBSOLETE In this example, we've assumed your program is in a file called
+@c OBSOLETE @file{myfoo}. Note that the filename given as the last argument to
+@c OBSOLETE @code{target amd-eb} should be the name of the program as it appears to DOS.
+@c OBSOLETE In our example this is simply @code{MYFOO}, but in general it can include
+@c OBSOLETE a DOS path, and depending on your transfer mechanism may not resemble
+@c OBSOLETE the name on the Unix side.
+@c OBSOLETE
+@c OBSOLETE At this point, you can set any breakpoints you wish; when you are ready
+@c OBSOLETE to see your program run on the 29K board, use the @value{GDBN} command
+@c OBSOLETE @code{run}.
+@c OBSOLETE
+@c OBSOLETE To stop debugging the remote program, use the @value{GDBN} @code{detach}
+@c OBSOLETE command.
+@c OBSOLETE
+@c OBSOLETE To return control of the PC to its console, use @code{tip} or @code{cu}
+@c OBSOLETE once again, after your @value{GDBN} session has concluded, to attach to
+@c OBSOLETE @code{EBMON}. You can then type the command @code{q} to shut down
+@c OBSOLETE @code{EBMON}, returning control to the DOS command-line interpreter.
+@c OBSOLETE Type @kbd{CTTY con} to return command input to the main DOS console,
+@c OBSOLETE and type @kbd{~.} to leave @code{tip} or @code{cu}.
+@c OBSOLETE
+@c OBSOLETE @node Remote Log
+@c OBSOLETE @subsubsection Remote log
+@c OBSOLETE @cindex @file{eb.log}, a log file for EB29K
+@c OBSOLETE @cindex log file for EB29K
+@c OBSOLETE
+@c OBSOLETE The @code{target amd-eb} command creates a file @file{eb.log} in the
+@c OBSOLETE current working directory, to help debug problems with the connection.
+@c OBSOLETE @file{eb.log} records all the output from @code{EBMON}, including echoes
+@c OBSOLETE of the commands sent to it. Running @samp{tail -f} on this file in
+@c OBSOLETE another window often helps to understand trouble with @code{EBMON}, or
+@c OBSOLETE unexpected events on the PC side of the connection.
@node ARM
@subsection ARM
projects / binutils-gdb.git / commitdiff