This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [PATCH 18/18] document the new VxWorks port
- From: Joel Brobecker <brobecker at adacore dot com>
- To: Eli Zaretskii <eliz at gnu dot org>
- Cc: gdb-patches at sourceware dot org
- Date: Thu, 3 Mar 2011 16:16:00 +0400
- Subject: Re: [PATCH 18/18] document the new VxWorks port
- References: <1298569763-18784-1-git-send-email-brobecker@adacore.com> <1298569763-18784-19-git-send-email-brobecker@adacore.com> <838vx5rzf8.fsf@gnu.org>
Eli,
Thanks for the review.
I think I addressed all of your comments, except one, which I will
reply to below. You'll find 2 patches, a first one which just shows
the changes I made on top of the first patch, and then the second
one, which shows the new patch, in its entirety. Hopefully this will
help you find quickly which changes were made, and verify that all
your comments have been addressed correctly.
> > +@table @code
> > +@kindex info partitions
> > +@item info partitions
>
> Why not "info wtx partitions", or some other variant to make sure this
> is VxWorks specific? "info partitions" is too general to reserve for
> a niche platform.
The reason why this hasn't been put under the "wtx" prefix is because
I don't consider partitions to be a VxWorks-specific concept. I don't
know very much about the specifics, but I think that partitions are
defined by ARINC 653. But, beyond ARINC 653, I think that this concept
can be used in many areas, and we might find one day another platform
where the concept of partitions is used as well.
Right now, the implementation we have in GDB is ad hoc, and WTX calls
are hard-coded inside the partition support code. However, my plan,
if I have the courage and enough rainy days, is to make that entirely
generic, so that the code can be shared with other platforms that might
come up which also provides a form of partition support.
I hope that answers your concerns.
Thanks,
--
Joel
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 493f338..02189c1 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1903,7 +1903,9 @@ argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of
If you are running your program in an execution environment that
supports processes, @code{run} creates an inferior process and makes
that process run your program. In some environments without processes,
-@code{run} jumps to the start of your program. Other targets,
+@code{run} jumps to the start of your program. On VxWorks, it
+spawns a new VxWorks task which starts executing using the first
+argument as the entry point (@pxref{VxWorks}). Other targets,
like @samp{remote}, are always running. If you get an error
message like this one:
@@ -2322,6 +2324,10 @@ targets.) The command takes as argument a process ID. The usual way to
find out the @var{process-id} of a Unix process is with the @code{ps} utility,
or with the @samp{jobs -l} shell command.
+On VxWorks, where we debug VxWorks tasks rather than processes,
+the Vxworks task ID is used to identify the task that needs to
+be debugged (@pxref{VxWorks}).
+
@code{attach} does not repeat if you press @key{RET} a second time after
executing the command.
@end table
@@ -17946,6 +17952,7 @@ sends all debugging comands (resume task execution, read memory, read
register, @dots{}) through the Target Server.
@subsubsection Debugging on VxWorks 5.5
+@cindex VxWorks 5.5, debugging on
Debugging a program on VxWorks 5.5 is performed by connecting to
the Target Server first. To establish this connection, use the
@@ -17964,10 +17971,12 @@ from these modules.
VxWorks does not have a concept of processes, or even programs, like
most Operating Systems do. Instead of running a program, one spawns
-a @dfn{task} (a.k.a. a thread), usually using a symbol name as the entry
-point for that thread. Every task created can be regarded as a kernel
-thread, since it shares memory and code with the rest of the system.
+a @dfn{task} (a.k.a.@: a thread), usually using a symbol name as
+the entry point for that thread. Every task created can be regarded
+as a kernel thread, since it shares memory and code with the rest of
+the system.
+@kindex run, with VxWorks
To create a new task under debugger control, use the @code{run}
command, passing as the first parameter the name of the symbol
to use as the entry point (all other parameters are ignored):
@@ -17977,6 +17986,7 @@ to use as the entry point (all other parameters are ignored):
[@dots{}]
@end smallexample
+@kindex attach, with VxWorks
Instead of creating a new task, it is also possible to attach the
debugger to an already existing task, using the @code{attach} command.
The equivalent of the Unix process ID is the task ID on VxWorks, and
@@ -17999,15 +18009,15 @@ A list of all tasks currently running on the target can be obtained
using the @code{info wtx threads} command.
@table @code
-@kindex info wtx threads
-@item info wtx threads
-Print the list of threads currently running on the target.
-Each line represents a thread, and contains 2 space-separated
+@kindex info wtx vxworks-tasks
+@item info wtx vxworks-tasks
+Print the list of VxWorks tasks currently running on the target.
+Each line represents a task, and contains 2 space-separated
elements. The first element is the task ID, and the second
is the task name.
@smallexample
-(@value{GDBP}) info wtx threads
+(@value{GDBP}) info wtx vxworks-tasks
0xf710190 tShell
0xf712430 tWdbTask
0xf715600 tTelnetd
@@ -18015,6 +18025,13 @@ is the task name.
@end smallexample
@end table
+@table @code
+@kindex info wtx threads
+@item info wtx threads
+This command is an alias of @code{info wtx vxworks-tasks}, provided
+to help upward-compatibility.
+@end table
+
GDB offers several modes for debugging VxWorks tasks:
@table @dfn
@@ -18025,8 +18042,8 @@ In this mode, only a single tasks is being debugged. Any other tasks,
including new tasks created by the task being debugged, are simply
ignored (their execution is not controlled by the debugger).
-@cindex VxWorks, Multitasks Mode Debugging
-@item Multitasks Mode
+@cindex VxWorks, Multi-tasks Mode Debugging
+@item Multi-tasks Mode
This is a mode specific to Ada programs where the debugger simulates
the concept of debugging a process. This is useful when trying to debug
an Ada program that uses the multi-tasking features of Ada.
@@ -18039,9 +18056,9 @@ are automatically stopped and put under debugger control. New tasks
being spawned by the Ada "program" are also automatically taken under
debugger control.
-This mode is specific to Ada programs because it, because it relies
-on the Ada runtime in order to extract the list of tasks currently
-running as part of the Ada program.
+This mode is specific to Ada programs because it relies on the Ada
+runtime in order to extract the list of tasks currently running
+as part of the Ada program.
@cindex VxWorks, System Mode Debugging
@item The System Mode
@@ -18056,15 +18073,16 @@ To leave System Mode, use @code{detach}.
@kindex set multi-tasks-mode
@item set multi-tasks-mode [on|off]
If @code{on}, activate multi-tasks mode. The default is @code{off}.
-This setting should be properly set before using the @code{attach}
-or @code{run} command. As long as GDB controls the execution of one
-or more tasks, attempting to change this setting will result in an
-error.
+This mode should be set before using the @code{attach} or @code{run}
+command, and it is not possible to change the debugging mode while
+controlling one or more tasks (attempting to do so will result in
+an error).
This setting is ignored when debugging in System Mode.
@end table
@subsubsection Debugging on VxWorks 653
+@cindex VxWorks 653, debugging on
Debugging on VxWorks 653 is very similar to debugging on VxWorks 5,
and the commands available for VxWorks 5 are also generally available
@@ -18117,7 +18135,7 @@ requested symbols - for more information, see your Tornado 653
Manuals).
@smallexample
-(@value{GDBP}) maintenance info link-path
+(@value{GDBP}) maintenance info link-path
Partition Name [Link Path]
0x356738 coreOS [.]
0xd799f0 ssl [.]
@@ -18141,7 +18159,7 @@ the debugging session. The default is @code{gdb}.
@kindex show wtx tool-name
@item show wtx tool-name
-Display the tool name used when establishing a connection with the
+Print the tool name used when establishing a connection with the
WTX server.
@kindex set wtx load-timeout
@@ -18162,7 +18180,7 @@ control. The default is 0x10000 bytes.
@kindex show wtx stack-size
@item show wtx stack-size
-Display the size of the stack allocated when spawning a new task from
+Print the size of the stack allocated when spawning a new task from
the debugger (using the @code{run} command).
@kindex set wtx task-options
@@ -18173,7 +18191,7 @@ Change the options argument used when spawning a new task from
@kindex show wtx task-options
@item show wtx task-options
-Show the options argument used when spawning a new task from
+Print the options argument used when spawning a new task from
@value{GDBN}.
@kindex set wtx task-priority
@@ -18260,8 +18278,8 @@ maintainers wishing to instrument the part of the code in
@item set wtx debug events @var{level}
If @var{level} is nonzero, print debug traces related to WTX event
handling. The events being traced are all the events that wtxEventGet
-returns (Eg: breakpoint events, watchpoint events, new modules loaded,
-etc@dots{}).
+returns (e.g., breakpoint events, watchpoint events, new modules loaded,
+@dots{}).
@kindex show wtx debug events
@item show wtx debug events
@@ -18301,16 +18319,17 @@ Set the verbosity level of error messages from the TCL interpreter.
@kindex show wtx debug tcl
@item show wtx debug tcl
-Show the verbosity level of error messages from the TCL interpreter.
+Print the verbosity level of error messages from the TCL interpreter.
@end table
@subsubsection Debugging on VxWorks 6
+@cindex VxWorks 6, debugging on
Debugging on VxWorks 6 follows the same principles as those for
debugging VxWorks 5. The main difference is that @value{GDBN} needs
-to connect to a DFW server in addition to the Target Server. The
-@dfn{DFW server} is another server running on the host (see your
+to connect to a @dfn{DFW server} in addition to the Target Server.
+The DFW server is another server running on the host (see your
VxWorks 6 Manuals for more information about this process).
To start a debugging session, use the @code{target dfw} command.
@@ -18384,8 +18403,8 @@ Show whether to show the responses sent by the DFW server.
@item set dfw debug unknown-identifiers
@item set dfw debug unknown-identifiers on
Print a warning if the DFW server returns an identifier
-that is not known for task types (e.g. ``RTP''), task states
-(e.g. ``running''), event kinds (e.g. ``download-failed'').
+that is not known for task types (e.g., ``RTP''), task states
+(e.g., ``running''), event kinds (e.g., ``download-failed'').
@item set dfw debug unknown-identifiers off
Disable warnings about unknown task types, task states, event kinds.
commit 02a260e67a68b8ac8b1a5300e5c1df011e0cd364
Author: Joel Brobecker <brobecker@adacore.com>
Date: Thu Feb 24 12:35:43 2011 -0500
document the new VxWorks port
The VxWorks documentation was completely out of date, so I rewrote it
from scratch. I tried to organize it in a logical way, introducing
some of the concepts about VxWorks, to make the port a little alien
to someone who is not familiar with this OS.
I've also included a NEWS entry.
gdb/ChangeLog:
* NEWS: Add entry documenting the new VxWorks ports.
gdb/doc/ChangeLog:
* gdb.texinfo (Starting): Add reference to VxWorks node.
(Attach): Likewise.
(VxWorks): Rewrite the VxWorks documentation.
diff --git a/gdb/NEWS b/gdb/NEWS
index fb36383..f442d98 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -162,6 +162,14 @@ ia64 HP-UX ia64-*-hpux*
Analog Devices, Inc. Blackfin Processor bfin-*
+VxWorks 653 i[34567]86-*-vxworks653
+ powerpc-*-vxworks653
+VxWorks 6.x i[34567]86-*-vxworks6*
+ powerpc-*-vxworks6*
+ e500*-*-vxworks6*
+VxWorks 5.x (x >= 4) i[34567]86-*-vxworks*
+ powerpc-*-vxworks*
+
* Ada task switching is now supported on sparc-elf targets when
debugging a program using the Ravenscar Profile. For more information,
see the "Tasking Support when using the Ravenscar Profile" section
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index ad6e2f4..02189c1 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1903,7 +1903,9 @@ argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of
If you are running your program in an execution environment that
supports processes, @code{run} creates an inferior process and makes
that process run your program. In some environments without processes,
-@code{run} jumps to the start of your program. Other targets,
+@code{run} jumps to the start of your program. On VxWorks, it
+spawns a new VxWorks task which starts executing using the first
+argument as the entry point (@pxref{VxWorks}). Other targets,
like @samp{remote}, are always running. If you get an error
message like this one:
@@ -2322,6 +2324,10 @@ targets.) The command takes as argument a process ID. The usual way to
find out the @var{process-id} of a Unix process is with the @code{ps} utility,
or with the @samp{jobs -l} shell command.
+On VxWorks, where we debug VxWorks tasks rather than processes,
+the Vxworks task ID is used to identify the task that needs to
+be debugged (@pxref{VxWorks}).
+
@code{attach} does not repeat if you press @key{RET} a second time after
executing the command.
@end table
@@ -17935,165 +17941,510 @@ various real-time operating systems.
@node VxWorks
@subsection Using @value{GDBN} with VxWorks
-
@cindex VxWorks
-@table @code
+Debugging on VxWorks is supported on VxWorks 5.5, all versions of
+Vworks 6 starting with version 6.4, and VxWorks 653. @value{GDBN}
+does not connect directly to the target running VxWorks, but instead
+relies on the @dfn{Target Server}, which is a process running on the
+host. The debugger establishes a connection with that process, and
+sends all debugging comands (resume task execution, read memory, read
+register, @dots{}) through the Target Server.
+
+@subsubsection Debugging on VxWorks 5.5
+@cindex VxWorks 5.5, debugging on
-@kindex target vxworks
-@item target vxworks @var{machinename}
-A VxWorks system, attached via TCP/IP. The argument @var{machinename}
-is the target system's machine name or IP address.
+Debugging a program on VxWorks 5.5 is performed by connecting to
+the Target Server first. To establish this connection, use the
+@code{target wtx} command (@dfn{WTX} is the name of the protocol
+used to communicate with the Target Server):
+@table @code
+@kindex target wtx
+@item target wtx @var{target-server-name}
+Connect @value{GDBN} to a Target Server whose name is
+@var{target-server-name}. Once the connection is established,
+@value{GDBN} queries the list of modules loaded on the target, and
+then proceeds to load the symbol table and debugging information
+from these modules.
@end table
-On VxWorks, @code{load} links @var{filename} dynamically on the
-current target system as well as adding its symbols in @value{GDBN}.
+VxWorks does not have a concept of processes, or even programs, like
+most Operating Systems do. Instead of running a program, one spawns
+a @dfn{task} (a.k.a.@: a thread), usually using a symbol name as
+the entry point for that thread. Every task created can be regarded
+as a kernel thread, since it shares memory and code with the rest of
+the system.
-@value{GDBN} enables developers to spawn and debug tasks running on networked
-VxWorks targets from a Unix host. Already-running tasks spawned from
-the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
-both the Unix host and on the VxWorks target. The program
-@code{@value{GDBP}} is installed and executed on the Unix host. (It may be
-installed with the name @code{vxgdb}, to distinguish it from a
-@value{GDBN} for debugging programs on the host itself.)
+@kindex run, with VxWorks
+To create a new task under debugger control, use the @code{run}
+command, passing as the first parameter the name of the symbol
+to use as the entry point (all other parameters are ignored):
-@table @code
-@item VxWorks-timeout @var{args}
-@kindex vxworks-timeout
-All VxWorks-based targets now support the option @code{vxworks-timeout}.
-This option is set by the user, and @var{args} represents the number of
-seconds @value{GDBN} waits for responses to rpc's. You might use this if
-your VxWorks target is a slow software simulator or is on the far side
-of a thin network line.
-@end table
-
-The following information on connecting to VxWorks was current when
-this manual was produced; newer releases of VxWorks may use revised
-procedures.
-
-@findex INCLUDE_RDB
-To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
-to include the remote debugging interface routines in the VxWorks
-library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
-VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
-kernel. The resulting kernel contains @file{rdb.a}, and spawns the
-source debugging task @code{tRdbTask} when VxWorks is booted. For more
-information on configuring and remaking VxWorks, see the manufacturer's
-manual.
-@c VxWorks, see the @cite{VxWorks Programmer's Guide}.
-
-Once you have included @file{rdb.a} in your VxWorks system image and set
-your Unix execution search path to find @value{GDBN}, you are ready to
-run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or
-@code{vxgdb}, depending on your installation).
+@smallexample
+(@value{GDBP}) run simple_main
+[@dots{}]
+@end smallexample
-@value{GDBN} comes up showing the prompt:
+@kindex attach, with VxWorks
+Instead of creating a new task, it is also possible to attach the
+debugger to an already existing task, using the @code{attach} command.
+The equivalent of the Unix process ID is the task ID on VxWorks, and
+these IDs should be used to identify the task that needs to be
+debugged.
@smallexample
-(vxgdb)
+(@value{GDBP}) attach 0xf70b0f0
+Attaching to task 0xf70b0f0.
+[@dots{}]
@end smallexample
-@menu
-* VxWorks Connection:: Connecting to VxWorks
-* VxWorks Download:: VxWorks download
-* VxWorks Attach:: Running tasks
-@end menu
+As a convenience, GDB allows the use of the task name as a parameter
+to the @code{attach} command, in place of the task ID. When a task
+name is specified, the first task whose name matches is selected.
+If there are more than one tasks with the same name, the selection
+process is random.
-@node VxWorks Connection
-@subsubsection Connecting to VxWorks
+A list of all tasks currently running on the target can be obtained
+using the @code{info wtx threads} command.
-The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
-network. To connect to a target whose host name is ``@code{tt}'', type:
+@table @code
+@kindex info wtx vxworks-tasks
+@item info wtx vxworks-tasks
+Print the list of VxWorks tasks currently running on the target.
+Each line represents a task, and contains 2 space-separated
+elements. The first element is the task ID, and the second
+is the task name.
@smallexample
-(vxgdb) target vxworks tt
+(@value{GDBP}) info wtx vxworks-tasks
+0xf710190 tShell
+0xf712430 tWdbTask
+0xf715600 tTelnetd
+[@dots{}]
@end smallexample
+@end table
-@need 750
-@value{GDBN} displays messages like these:
+@table @code
+@kindex info wtx threads
+@item info wtx threads
+This command is an alias of @code{info wtx vxworks-tasks}, provided
+to help upward-compatibility.
+@end table
+
+GDB offers several modes for debugging VxWorks tasks:
+
+@table @dfn
+
+@cindex VxWorks, Task Mode Debugging
+@item Task Mode
+In this mode, only a single tasks is being debugged. Any other tasks,
+including new tasks created by the task being debugged, are simply
+ignored (their execution is not controlled by the debugger).
+
+@cindex VxWorks, Multi-tasks Mode Debugging
+@item Multi-tasks Mode
+This is a mode specific to Ada programs where the debugger simulates
+the concept of debugging a process. This is useful when trying to debug
+an Ada program that uses the multi-tasking features of Ada.
+
+When debugging in this mode, all Ada tasks controlled by the Ada
+run-time library are under @value{GDBN} control, and their execution
+is automatically stopped or resumed as needed. In particular, when
+attaching to a task, all associated tasks in the same Ada "program"
+are automatically stopped and put under debugger control. New tasks
+being spawned by the Ada "program" are also automatically taken under
+debugger control.
+
+This mode is specific to Ada programs because it relies on the Ada
+runtime in order to extract the list of tasks currently running
+as part of the Ada program.
+
+@cindex VxWorks, System Mode Debugging
+@item The System Mode
+
+In this mode, the debugger controls the entire system as one process,
+including part of the system such as the scheduler, interrupt handlers,
+etc. To enter System Mode, simply use the @code{attach system} command.
+To leave System Mode, use @code{detach}.
+@end table
+
+@table @code
+@kindex set multi-tasks-mode
+@item set multi-tasks-mode [on|off]
+If @code{on}, activate multi-tasks mode. The default is @code{off}.
+This mode should be set before using the @code{attach} or @code{run}
+command, and it is not possible to change the debugging mode while
+controlling one or more tasks (attempting to do so will result in
+an error).
+
+This setting is ignored when debugging in System Mode.
+@end table
+
+@subsubsection Debugging on VxWorks 653
+@cindex VxWorks 653, debugging on
+
+Debugging on VxWorks 653 is very similar to debugging on VxWorks 5,
+and the commands available for VxWorks 5 are also generally available
+for VxWorks 653.
+
+The one important distinction is the fact that VxWorks 653 provides
+the concept of @dfn{Partitions}, as defined by the ARINC 653
+specification. These partitions usually have their own address space,
+and allow the user to make sure that tasks running in one partition
+cannot affect tasks running on another partition (on VxWorks AE,
+which is an ancestor of VxWorks 653, these partitions were called
+@dfn{Protection Domains}, or @dfn{PD} in short). Please refer to your
+VxWorks 653 manual for more information about the various types of
+partitions and their use.
+
+@table @code
+@kindex info partitions
+@item info partitions
+Print the list of existing partitions on the target system. Each line
+corresponds to a partition, and contains its ID and name. An asterisk
+@samp{*} at the start of one of the lines indicates the current partition.
@smallexample
-Attaching remote machine across net...
-Connected to tt.
+(@value{GDBP}) info partitions
+ PD-ID Name
+* 0x356738 coreOS
+ 0xd799f0 ssl
+ 0xd7ae20 part1
+ 0xd80750 part2
@end smallexample
-@need 1000
-@value{GDBN} then attempts to read the symbol tables of any object modules
-loaded into the VxWorks target since it was last booted. @value{GDBN} locates
-these files by searching the directories listed in the command search
-path (@pxref{Environment, ,Your Program's Environment}); if it fails
-to find an object file, it displays a message such as:
+@kindex partition
+@item partition @var{id-or-name}
+Switch to the given partition. The @var{id-or-name} argument can
+be either the partition ID (an hexadecimal number), or its name.
+
+@smallexample
+(@value{GDBP}) partition part1
+[Switching to Partition part1 (0xd7ae20)]
+(@value{GDBP}) partition 0xd80750
+[Switching to Partition part2 (0xd80750)]
+@end smallexample
+
+@kindex maintenance info link-path
+@item maintenance info link-path
+This is a command mostly aimed at helping GDB maintainers. It prints
+the @dfn{link path} of each partition (the @dfn{Link Path} is a path
+associated to each partition, and is used by the loader to find
+requested symbols - for more information, see your Tornado 653
+Manuals).
@smallexample
-prog.o: No such file or directory.
+(@value{GDBP}) maintenance info link-path
+Partition Name [Link Path]
+ 0x356738 coreOS [.]
+ 0xd799f0 ssl [.]
+ 0xd7ae20 part1 [.:ssl:ssl]
+ 0xd80750 part2 [.:ssl]
@end smallexample
-When this happens, add the appropriate directory to the search path with
-the @value{GDBN} command @code{path}, and execute the @code{target}
-command again.
+@end table
+
+@subsubsection Commands and Settings Related to WTX
+
+The following Settings are provided:
+
+@table @code
+@kindex set wtx tool-name
+@item set wtx tool-name @var{name}
+This command can be used to change the name of the tool given to
+the Target Server when establishing the connection. This is only
+for documentation and logging purposes as this has no effect on
+the debugging session. The default is @code{gdb}.
+
+@kindex show wtx tool-name
+@item show wtx tool-name
+Print the tool name used when establishing a connection with the
+WTX server.
+
+@kindex set wtx load-timeout
+@item set wtx load-timeout @var{timeout}
+Change the timeout (in seconds) used when loading new modules on
+the target. The default is 30 seconds.
+
+@kindex show wtx load-timeout
+@item show wtx load-timeout
+Print the timeout duration used when loading modules on the target.
+
+@kindex set wtx stack-size
+@item set wtx stack-size @var{size}
+Change the stack size (in bytes) of the tasks spawned by the debugger
+(using the @code{run} command). This does not affect the stack size
+of a task spawned by other tasks, even if those tasks are under debugger
+control. The default is 0x10000 bytes.
+
+@kindex show wtx stack-size
+@item show wtx stack-size
+Print the size of the stack allocated when spawning a new task from
+the debugger (using the @code{run} command).
+
+@kindex set wtx task-options
+@item set wtx task-options @var{val}
+Change the options argument used when spawning a new task from
+@value{GDBN}. Bits in this options argument are defined in
+@file{wpwr/target/h/taskLib.h}. The default value is 0.
+
+@kindex show wtx task-options
+@item show wtx task-options
+Print the options argument used when spawning a new task from
+@value{GDBN}.
+
+@kindex set wtx task-priority
+@item set wtx task-priority @var{priority}
+Change the priority of new tasks spawned by the debugger. The default
+is 100.
+
+@kindex show wtx task-priority
+@item show wtx task-priority
+Print the task priority used when spawning new tasks from the debugger.
+
+@end table
+
+Some commands are also available to query the Target Server about
+the system running on the target.
-@node VxWorks Download
-@subsubsection VxWorks Download
+@table @code
-@cindex download to VxWorks
-If you have connected to the VxWorks target and you want to debug an
-object that has not yet been loaded, you can use the @value{GDBN}
-@code{load} command to download a file from Unix to VxWorks
-incrementally. The object file given as an argument to the @code{load}
-command is actually opened twice: first by the VxWorks target in order
-to download the code, then by @value{GDBN} in order to read the symbol
-table. This can lead to problems if the current working directories on
-the two systems differ. If both systems have NFS mounted the same
-filesystems, you can avoid these problems by using absolute paths.
-Otherwise, it is simplest to set the working directory on both systems
-to the directory in which the object file resides, and then to reference
-the file by its name, without any path. For instance, a program
-@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
-and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
-program, type this on VxWorks:
+@kindex info wtx
+@item info wtx
+@item info wtx version
+Display the version of the WTX protocol in use.
@smallexample
--> cd "@var{vxpath}/vw/demo/rdb"
+(@value{GDBP}) info wtx
+WTX protocol version 2
@end smallexample
-@noindent
-Then, in @value{GDBN}, type:
+@kindex info wtx vxworks-version
+@item info wtx vxworks-version
+Display the version of the VxWorks system running on the target.
@smallexample
-(vxgdb) cd @var{hostpath}/vw/demo/rdb
-(vxgdb) load prog.o
+(@value{GDBP}) info wtx vxworks-version
+VxWorks version 5.5
@end smallexample
-@value{GDBN} displays a response similar to this:
+@kindex info wtx target-server
+@item info wtx target-server
+Display the target specifications provided by the target server.
@smallexample
-Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
+(@value{GDBP}) info wtx target-server
+Target agent:
+version: 2.0
+max transfer size in bytes: 1372
+available agent modes: 3
+
+Runtime:
+name: VxWorks
+version: 5.5
+target processor type: 94
+has write protect: 0
+page size: 4096
+endianness: 1234
+BSP: Motorola MVME5110-2153 - MPC 7410
+boot file: myhost:/path/to/vxWorks
+target main memory base address: 0
+target memory size: 268435456
+number of memory regions: 0
+target server memory pool base: 0x1ff558
+target server memory pool size: 16646314
@end smallexample
-You can also use the @code{load} command to reload an object module
-after editing and recompiling the corresponding source file. Note that
-this makes @value{GDBN} delete all currently-defined breakpoints,
-auto-displays, and convenience variables, and to clear the value
-history. (This is necessary in order to preserve the integrity of
-debugger's data structures that reference the target system's symbol
-table.)
+@end table
-@node VxWorks Attach
-@subsubsection Running Tasks
+Some of the information (such as the list of tasks currently running
+on the system) can only be retrieved by using some of TCL procedures
+provided by VxWorks. A minimal TCL intepreter is therefore included
+in GDB.
-@cindex running VxWorks tasks
-You can also attach to an existing task using the @code{attach} command as
-follows:
+@table @code
+@kindex maintenance tcl
+@item maintenance tcl @code{tcl-command}
+Use the TCL interpreter to evaluate the @code{tcl-command}.
+@end table
-@smallexample
-(vxgdb) attach @var{task}
-@end smallexample
+Finally, the following commands may be useful to @value{GDBN}
+maintainers wishing to instrument the part of the code in
+@value{GDBN} responsible for supporting the WTX protocol.
-@noindent
-where @var{task} is the VxWorks hexadecimal task ID. The task can be running
-or suspended when you attach to it. Running tasks are suspended at
-the time of attachment.
+@table @code
+@kindex set wtx debug events
+@item set wtx debug events @var{level}
+If @var{level} is nonzero, print debug traces related to WTX event
+handling. The events being traced are all the events that wtxEventGet
+returns (e.g., breakpoint events, watchpoint events, new modules loaded,
+@dots{}).
+
+@kindex show wtx debug events
+@item show wtx debug events
+Print the current trace level for WTX event handling.
+
+@kindex set wtx debug objfiles
+@item set wtx debug objfiles @var{level}
+If @var{level} is nonzero, print debug traces related to module
+handling for WTX (modules are stored as @dfn{objfiles} in
+@value{GDBN}).
+
+@kindex show wtx debug objfiles
+@item show wtx debug objfiles
+Print th current trace level for WTX module handling.
+
+@kindex set wtx debug breakpoints
+@item set wtx debug breakpoints @var{level}
+If @var{level} is nonzero, print debug traces related to WTX
+breakpoint handling.
+
+@kindex show wtx debug breakpoints
+@item show wtx debug breakpoints
+Print the current trace level for WTX breakpoint event handling.
+
+@kindex set wtx debug watchpoints
+@item set wtx debug watchpoints @var{level}
+If @var{level} is nonzero, print debug traces related to WTX
+watchpoint handling.
+
+@kindex show wtx debug watchpoints
+@item show wtx debug watchpoints
+Print the current trace level for WTX watchpoint event handling.
+
+@kindex set wtx debug tcl
+@item set wtx debug tcl @var{level}
+Set the verbosity level of error messages from the TCL interpreter.
+
+@kindex show wtx debug tcl
+@item show wtx debug tcl
+Print the verbosity level of error messages from the TCL interpreter.
+
+@end table
+
+@subsubsection Debugging on VxWorks 6
+@cindex VxWorks 6, debugging on
+
+Debugging on VxWorks 6 follows the same principles as those for
+debugging VxWorks 5. The main difference is that @value{GDBN} needs
+to connect to a @dfn{DFW server} in addition to the Target Server.
+The DFW server is another server running on the host (see your
+VxWorks 6 Manuals for more information about this process).
+
+To start a debugging session, use the @code{target dfw} command.
+It will get both DFW and WTX connections established (therefore, do
+not use the @code{target wtx} command with VxWorks 6).
+
+@subsubsection Commands and Settings Related to DFW
+
+The following settings are provided:
+
+@table @code
+
+@kindex set dfw timeout
+@item set dfw timeout @var{duration}
+Change the timeout (in seconds) used when trying to read from the
+connection with the DFW server. The default value is 30 seconds.
+
+@kindex show dfw timeout
+@item show dfw timeout
+Show the duration in seconds before an attempt to read data from
+the DFW server should time out.
+
+@kindex set dfw server-name
+@item set dfw server-name @var{name}
+Set the name of the DFW server as registered in the WIND registry.
+By default, it is set to @code{dfw}; if only one DFW server is
+registered in the registry, GDB will connect to this server by
+default.
+
+@kindex show dfw server-name
+@item show dfw server-name
+Show the name of the DFW server.
+
+@end table
+
+The following commands may be useful to @value{GDBN} maintainers
+wishing to instrument the part of the code in @value{GDBN}
+responsible for supporting the DFW protocol.
+
+@table @code
+
+@kindex dfw send
+@item dfw send
+Send a request to the current DFW server.
+
+@kindex set dfw debug requests
+@item set dfw debug requests
+@item set dfw debug requests on
+Print the requests sent to the DFW server to stdout.
+
+@item set dfw debug requests off
+Do not print the requests sent to the DFW server to stdout.
+
+@kindex show dfw debug requests
+@item show dfw debug requests
+Show whether to show the requests sent to the DFW server.
+
+@kindex set dfw debug responses
+@item set dfw debug responses
+@item set dfw debug responses on
+Print the responses of the DFW server to stdout.
+
+@item set dfw debug responses off
+Do not print the responses of the DFW server to stdout.
+
+@kindex show dfw debug responses
+@item show dfw debug responses
+Show whether to show the responses sent by the DFW server.
+
+@kindex set dfw debug unknown-identifiers
+@item set dfw debug unknown-identifiers
+@item set dfw debug unknown-identifiers on
+Print a warning if the DFW server returns an identifier
+that is not known for task types (e.g., ``RTP''), task states
+(e.g., ``running''), event kinds (e.g., ``download-failed'').
+
+@item set dfw debug unknown-identifiers off
+Disable warnings about unknown task types, task states, event kinds.
+
+@kindex show dfw debug unknown-identifiers
+@item show dfw debug unknown-identifiers
+Show whether to warn about unknown task types, task states, event kinds.
+
+@end table
+
+@subsubsection VxWorks Module Handling
+@cindex VxWorks, Module Handling
+
+Unlike most Operating Systems, the loading of modules in memory has
+to be performed manually by the user. Modules can be a self-contained
+program, or just part of a program consisting of multiple modules
+(this is similar to programs depending on shared libraries).
+
+To load a new module on the target, use the @code{load} command.
+In addition to loading the module on the target, the debugger will
+also load its symbol table and debugging information.
+
+Modules may also be unloaded at any time, using the @code{unload}
+command.
+
+@table @code
+@kindex wtx add-symbol-file
+@item wtx add-symbol-file @var{file}
+This command is similar to the @code{add-symbol-file} command, except
+that it does not require base addresses to be provided. Instead,
+these addresses are automatically computed based on some information
+provided by the Target Server.
+
+This command is normally rarely needed, since GDB should
+automatically load the symbols from all modules either when
+connecting to the target, or when the module is loaded on the
+target. But this may become useful when the module fullpath
+provided by the target server does not correspond to the
+module's fullpath on the host where GDB is running.
+@end table
@node Embedded Processors
@section Embedded Processors