[PATCH 18/18] document the new VxWorks port

Joel Brobecker
2011-02-24T17:59:37Z

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 (VxWorks): Rewrite the VxWorks documentation.
---
gdb/NEWS | 8 +
gdb/doc/gdb.texinfo | 554 ++++++++++++++++++++++++++++++++++++++++----------
2 files changed, 451 insertions(+), 111 deletions(-)

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 32454c3..ca2cb18 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -17935,165 +17935,497 @@ 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.

-@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.
+@subsubsection Debugging on VxWorks 5.5

+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.)
+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:
+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 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
+elements. The first element is the task ID, and the second
+is the task name.

@smallexample
-(vxgdb) target vxworks tt
+(@value{GDBP}) info wtx threads
+0xf710190 tShell
+0xf712430 tWdbTask
+0xf715600 tTelnetd
+[@dots{}]
@end smallexample
+@end table

-@need 750
-@value{GDBN} displays messages like these:
+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, Multitasks Mode Debugging
+@item Multitasks 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, 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 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 setting is ignored when debugging in System Mode.
+@end table
+
+@subsubsection Debugging on VxWorks 653
+
+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
-prog.o: No such file or directory.
+(@value{GDBP}) partition part1
+[Switching to Partition part1 (0xd7ae20)]
+(@value{GDBP}) partition 0xd80750
+[Switching to Partition part2 (0xd80750)]
@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.
+@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
+(@value{GDBP}) maintenance info link-path
+Partition Name [Link Path]
+ 0x356738 coreOS [.]
+ 0xd799f0 ssl [.]
+ 0xd7ae20 part1 [.:ssl:ssl]
+ 0xd80750 part2 [.:ssl]
+@end smallexample
+
+@end table
+
+@subsubsection Commands and Settings Related to WTX
+
+The following Settings are provided:

-@node VxWorks Download
-@subsubsection VxWorks Download
+@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
+Display 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.

-@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 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
+Display 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
+Show 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.
+
+@table @code
+
+@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 tcl
+@item 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 (Eg: breakpoint events, watchpoint events, new modules loaded,
+etc@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
+Show the verbosity level of error messages from the TCL interpreter.
+
+@end table
+
+@subsubsection Debugging on VxWorks 6
+
+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
+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
--
1.7.0.4