From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 11722 invoked by alias); 24 Feb 2011 17:59:37 -0000 Received: (qmail 11710 invoked by uid 22791); 24 Feb 2011 17:59:34 -0000 X-SWARE-Spam-Status: No, hits=-0.6 required=5.0 tests=AWL,BAYES_50,TW_BJ,TW_WT,T_RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from rock.gnat.com (HELO rock.gnat.com) (205.232.38.15) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 24 Feb 2011 17:59:26 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by filtered-rock.gnat.com (Postfix) with ESMTP id 979AE2BADF3; Thu, 24 Feb 2011 12:59:24 -0500 (EST) Received: from rock.gnat.com ([127.0.0.1]) by localhost (rock.gnat.com [127.0.0.1]) (amavisd-new, port 10024) with LMTP id p6QUy1N6Ti52; Thu, 24 Feb 2011 12:59:24 -0500 (EST) Received: from kwai.gnat.com (kwai.gnat.com [205.232.38.4]) by rock.gnat.com (Postfix) with ESMTP id 826042BADE1; Thu, 24 Feb 2011 12:59:24 -0500 (EST) Received: by kwai.gnat.com (Postfix, from userid 4233) id 8236D94677; Thu, 24 Feb 2011 12:59:24 -0500 (EST) From: Joel Brobecker To: gdb-patches@sourceware.org Cc: Joel Brobecker Subject: [PATCH 18/18] document the new VxWorks port Date: Thu, 24 Feb 2011 18:04:00 -0000 Message-Id: <1298569763-18784-19-git-send-email-brobecker@adacore.com> In-Reply-To: <1298569763-18784-1-git-send-email-brobecker@adacore.com> References: <1298569763-18784-1-git-send-email-brobecker@adacore.com> Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2011-02/txt/msg00714.txt.bz2 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