Wind River extensions to GDB/MI for multi-process debugging

[Pawel Piech <pawel dot piech at windriver dot com>]

Hi All,
I've put together a short document with an overview of our extensions to
GDB/MI relevant to multi-process/multi-core debugging.  It took me ages
to get necessary approvals to share this document with the community but
it finally went through.  I hope that it'll be helpful to the community
in updating the MI protocol for related functionality in GDB.

Cheers,
Pawel

P.S. I had to covert the doc from HTML, so some of the formatting was lost.

   Copyright (c) 2003-2008 Wind River Systems, Inc.

Overview of Wind River Systems debugger's extensions to the GDB/MI protocol to
                      support debugging multiple targets.

   This document is intended to provide the background and the general
   philosophy behind the DFW extensions to the protocol.  It contains
   information copied from various DFW reference documents which were
   written at different times, so it may not reflect the current state of
   the DFW protocol.

Info Retrieve

   One of the principal DFW extensions to the MI protocol is the info
   retrieve command.  This command is used by clients to read static and
   dynamic information about targets, processes, services, etc.  The
   following is an introduction for the info retrieval document:

   This document explains the -wrs-info-retrieve command and the
   -wrs-info-modify command. The DFW information retrieval command
   wrs-info-retrieve allows clients to access a wide-range of detailed
   information about the DFW itself and the targets for which it provides
   debugging services in a consistent, hierarchical format. This
   information includes the following:
    1. Information about which plug-ins (target, processor, OS) are
       available and their properties
    2. Information about which targets the DFW has connected to, and
       information about the cores (CPUs) for each of them.
    3. For each core that has been connected to, the DFW information
       retrieval command provides access to
         1. Dynamic information about the operating system and its
            objects (tasks, semaphores, etc. as applicable to the
            specific operating system.
         2. Dynamic information about the execution contexts (generic
            term for tasks/processes/threads as applicable to the
            specific operating system), which includes
              i. The object modules loaded for the context
             ii. The symbol information contained in the object modules
             iii. The current call stack information
             iv. Information about register-groups, registers, bit-fields
                 etc.
              v. Expression evaluation

   The wrs-info-modify command modifies certain DFW information (like
   register values, register bit-field values, expression values etc.)

   The information exposed by the wrs-info-retrieve command is structured
   in a tree format similar to a file system on a workstation. Hence, the
   command includes two parts:
    1. The part that identifies the portion of the tree for which
       information is desired. The information retrieval command defines
       a simple (yet powerful) language for specifying this.
    2. Additional options that may include
         1. Input parameters needed for some information retrieval (e.g.
            to retrieve information about evaluated expressions, the
            input parameter is the expression itself)
         2. Parameters that fine-tune the output (e.g. whether to print
            expression values/ register values in hex/octal etc. etc.)

   The output from the command for the returned information is also
   structured in a consistent manner using simple rules and is conformant
   to the general output format followed by other GDB-MI commands.
   The exact syntax of an info retrieve command is somewhat complicated
   because it has numerous options for formatting of the output, however
   an example of a typical command looks like this:
11-wrs-info-retrieve -t /Targets/vincent_ruz@van-gateau default:{Name,ThreadId,
Connected,Cores/*/{Name,Connected,OSInfo/{Name,Version,Description}}
11^done,i=["vincent_ruz@van-gateau","1","true",["Pentium","true","Linux","2.6",
"Linux for Intel"]] 

   Similarly the description of all the data that can be retrieved
   through this mechanism is too big to describe here, but a sample of
   this description looks like this:

   [1]Targets

   Dynamic information about the targets

   <Target1>

   The first target. The name of the node is the name of the target

   Name

   Name of the target

   ThreadId

   Thread-id assigned for the target-wide context

   Connected

   Is the target connected to?

   AvailableProcessors

   List of actual available cores on this target.

   [0]

   First available core

   Variant

   Core processor variant name

   Name

   Core name (designator)

   . . .

   Other available cores

   Cores

   Cores in the target

   [2]<Core1>

   First core in the target. Name of the node is the name of the core.
   (see table below for structure under core)

   . . .

   Other cores

   . . .

   Other targets

   IdInfo

   Information about TOS objects or execution contexts, which are
   represented at the DFW GDB/MI layer by "TOS object ids" (of which
   thread-ids are a sub-set). TOS object-ids include
    1. thread ids corresponding to execution contexts (including
       target-wide and core-wide contexts)
    2. ids corresponding to TOS specific objects (depending on the TOS)
       such as semaphores, memory regions etc

   To access information under this node, you need to provide the object
   id via the -id option.

   Id

   The object-id/thread-id.

   ParentId

   The object-id/thread-id of the object that is the parent of this node
   (e.g. if this object represents a Linux thread, then this would
   contain the thread-id of the Linux process that owns the thread)

   TargetId

   The thread-id of the target wide context for the target to which this
   object belongs to

   CoreId

   The thread-id of the core wide context for the core to which this
   object belongs to. If this object represents a target-wide context,
   this node is not applicable and would contain an empty value.

   [3]Target

   The node that represents the target to which the object belongs to.
   This is a link node to the node for the target under the /Targets
   sub-tree.

Use of contexts

   Throughout the info retrieve data and in other commands and events,
   DFW uses context IDs in a single namespace.  The contexts IDs are used
   to represent targets, cores, processes, threads, other OS objects,
   etc.  Using a single namespace for these IDs not only simplifies the
   format of commands and events, it also makes it much easier to examine
   and analyze logs of debug sessions.

Target State Change Events

Target Stopped Event

   Format:
*stopped,
     reason="breakpoint-hit",
     bkptno="<breakpointnumber>",
     thread-id="<actual_stoped_context>",
     frame={
         addr="<stopped_address>",func="<function_name>",
         args=[{name="<argument_name>",value="<value>"}],
         file="<file_name>",line="<line_number>",
         column="<column_number"},
     bkptlist=["<affected_breakpoint_list>"],
     container-thread-ids=["<affected container thread-ids>"],
     thread-ids=["<affected thread-ids>"]

   Synopsis:

   The stopped message indicates a target state change, the context
   'thread-id' has stopped. If the reason is 'breakpoint-hit', then
   bkptno and bkptlist are included, where bkptlist is the list of
   breakpoint ids that match on the stopped address. 'bkptno' is just the
   first entry in the bkptlist.

   All parameters in italics are optional fields to the event. The
   thread-id reported in the stopped event, will be the ID of the thread
   that hit the breakpoint.  The IDs in the thread-ids list report the
   affected, or stopped, contexts.   If a container-thread-id is
   reported, then the container (and all children) is stopped. The
   reported "thread-id" should never be a container context.
   'frame' is always present with at least an the 'addr' address. The
   fields 'func', 'args', 'file', 'line', and 'column' are only present
   if there is sufficient debug information at the stopped address.

   Example:
*stopped,
     reason="breakpoint-hit",
     bkptno="3",thread-id="5",
     frame={
         addr="0x102AC",func="Delete",
         args=[{name="this",value="0x2345"},{name="bp",value="0x1"},{name="pt",
value="@0x10004"}],
         file="/usr/sds762/tutppc/b_grid.cpp",line="52",column="0"},
     bkptlist=[3],
     container-thread-ids=[1],
     thread-ids=[]

Target Running Event 

*running,thread-id="2"

   The running messages indicates a target state change, the context
   'thread-id' has started running.  If the thread-id is of a container
   context, it means that all threads within that container started
   running.

Started/Exited Events

   Started event format:
=context-start,
     thread-id="<thread-id>",
     context-type="<object-type>",
     creator-id="<id of the creator context>",
     container-id="<id for the parent context>",
     symbol-context="<id for the symbol context>",
     system-id="<id for the given system context>"

   Started event Example:
=context-start,thread-id="4",context-type="Task",creator-id="3",container-id="2
",symbol-context="2",system-context="2"

   Exited event format:
=context-exited,thread-id="<thread-id>"

Target Definition Commands

  -target-select

   -target-select type parameters ...

   Synopsis:

   Creates a connection in the debug engine and allows this client to
   access it or allows the client to access an already existing
   connection in the debug engine.

   The syntax for the preliminary release is limited as shown below. The
   command starts and connects to the WindISS simulator for the PPC8260
   target.

 -target-select wrs-remote-dfw -params={}
 -target-select wrs-remote-dfw targetDefinitionName


   This command connects to the target.

   Result:

 -target-select wrs-remote-dfw defaultTarget
 =connected,thread-id="1",def-name="defaultTarget"
 =connected,thread-id="2",def-name="defaultTarget",core-name="MPC8260",system-c
ontext-thread-id="3"
 ^done,connected-cores=[{core-name="MPC8260",thread-id="2"}]


   There will be a {coreName= and system-context-thread-id= if available}
   tuples for each core on the target.

   Out-of-Band-Record:

   Notifications for target connect and core stopped if the new target is
   created.

 =connected,thread-id="1"


   Errors:

 too few parameters:
 -target-select wrs-remote-dfw
 ^error,message="Invalid argument list: {0} {1}",parameters=["target-select","w
rs-remote-dfw"]
 incorrect parameters:
 -target-select remote -param={}
 ^error,message="Invalid command argument: {0} {1},parameters=["target-select",
"remote"]


   See also: 
          [4]Target Connection Events and [5]Target State Change Events

  -wrs-target-define

 -wrs-target-define ( defName | -n ) tgtPlugin
 [-tgt targetParameterString ]
 ( -auto-cpu-all |
 ( -cpu coreName (cpuPlugin | -auto-cpu) [cpuParameterString] )*
 ( -tos coreName tosPlugin [tosParameterString] )* )


   Synopsis:

   Creates a target definition with the specified parameters. If
   "defName" is specified, then defName is the name of the definition.
   This name will be used in [6]-wrs-target-connect and [7]-target-select
   commands.

   If the -n option is used, then a unique name is generated that is
   different than all currently existing definition names. The generated
   name is returned as part of the command results.

   The "tgtPlugin" is the name of the target connection plugin. For
   example, "ocdtargetplugin" is the name of the on-chip debug connection
   plugin.

   The targetParameterString is a string of parameters that configures
   the target connection plugin. The exact contents of the string depends
   on the target connection plugin. ( See [8]OCD Target Plugin Connect
   String )

   Use the -auto-cpu-all option if the coreName(s) are not know but the
   user just wants to connect to all cores on the specified target.

   There can be zero or multiple specifications of CPU and Target OS
   plugins.

   A CPU specification consists of a coreName, a CPU plugin name and an
   optional CPU parameter string. The contents of the parameter string
   depends on the CPU plugin.

   If the -auto-cpu ise used in place of a name for the cpu plugin-in,
   then DFW will use the target properties to determine the processor
   variant associated with the specified CoreName.

   The coreName is either the DesignatorName of a core on a target or is
   the processor variant name. In a multi-core situation, multiple cores
   may be of the same variant so the DesignatorNames must be used to
   uniquely identify the cores.

   A TOS specification consists of a coreName, a TOS plugin name, and an
   optional TOS parameter string. The contents of the parameter string
   depends on the TOS plugin.

 -wrs-target-define 8260Simulator ocdtargetplugin
 -tgt "DEVICE='Wind River ISS'"
 -cpu MPC8260 82xxcpuplugin


   The above example defines a connection to a simulator for the MPC8260.
   Note that the command is shown on multiple lines for clarity. In a
   real command, all the options would be on one line.

 -wrs-target-define 8245-AL-3 ocdtargetplugin
 -tgt "DEVICE='Wind River ICE',STYLE='ETHERNET',
 ADDR='172.18.10.87',
 BFNAME="f:/windriver/windpoweride/config/boardfiles/PowerPC/82xx/WindRiver_SBC
/WindRiver_SBC8245.brd'"
 -cpu U1 82xxcpuplugin


   The above example defines a connection to a single board target
   containing an PowerPC MPC8245 processor. The name of the definition is
   "8245-AL-3". The target connection plugin is "ocdtargetplugin". The
   target parameter string is shown on multiple lines but it would really
   be all one line. This particular string says the connection is done
   via a "Wind River ICE" over an ETHERNET connection. The address of the
   ICE unit is 172.18.10.87. The board file to use for the connection is
   the long name as shown above. Currently, the pathname must be an
   absolute path name.

   If backslashes are used in the file name, they must be escaped. It
   seems easier to just use forward slashes.

   The CPU coreName is U1. This corresponds to the core designator name
   used in the board definition file. In this particular case, since
   there is only one core, the name MPC8245 could have been used instead.
   The CPU plugin to use is named 82xxcpuplugin.

   The connection parameters are not verified at the time of the
   definition. When the target is actually connected to, there may be
   errors returned from the target and cpu plugins.

   Result:

 -done,defName="definitionName"


   This command only creates or alters an existing definition. No
   connections are affected as a result of this command.

   If a definition name is used for a connection that is currently
   connected, errors may result if there is an attempt to change
   something that is currently connected. The command can be used to add
   or delete cores and TOS awareness.

   Out-of-Band-Record:

   No out of band records are generated as a result of this command.

   Errors:

     * Missing parameters
     * Trying to change parameters for a connected target
     * Trying to change parameters for a connected core
     * Trying to change parameters for a connected TOS
     * Unrecognized options

   See also: 
          [9]-target-select, [10]-wrs-target-connect,
          [11]-wrs-target-disconnect

  -wrs-target-connect

   -wrs-target-connect definitionName [ -tgt | -cpu coreName | -tos
   coreName ]

   Synopsis:

   This command can be used to do one of four things:

   If only the definitionName is given, then the DFW target component for
   the connection is created.

   If the -tgt option is specified, then the target connection is
   actually performed. No cores are connected, but the target connection
   plugin is called.

   If the -cpu option is specified, then the indicated core is loaded and
   connected.

   If the -tos option is specified, then the indicated TOS is loaded and
   connected.

   This command does not wait for the connection events to occur before
   returing. The client will have to handle these events as they occur.

   If a currently connected target is connected, an error results.

   Result:

   ^done

   Out-of-Band-Record:

   Connected event.

   Core connection results in running or stopped.

   TOS connection has no out-of-band records.

   Target creation has no out-of-band records.

   Errors:

     * invalid definition name
     * invalid core name
     * invalid TOS core name
     * connection parameter errors.
     * target or core or TOS is already connected

  -wrs-target-disconnect

   -wrs-target-disconnect definitionName [ -tgt | -cpu coreName | -tos
   coreName ]

   Synopsis:

   This command can be used to do one of four things:

   If only the definitionName is given, then the DFW target component for
   the connection is destroyed.

   If the -tgt option is specified, then the target disconnection is
   actually performed. All cores are disconnected.

   If the -cpu option is specified, then the indicated core is
   disconnected.

   If the -tos option is specified, then the indicated TOS is
   disconnected.

   Result:

   ^done

   Out-of-Band-Record:

   Depending on what is done, some out-of-band-records will occur.

   Target disconnection results in:

   Connection Lost event.

   Core and TOS disconnection has no out-of-band records.

   Target destruction has no out-of-band records.

   Errors:

     * invalid definition name
     * invalid core name
     * invalid TOS core name
     * target or core or TOS is not connected or created

Target Connection Events

   Target Connected Event

=connected,thread-id="1"

   The connection plugin has detected that the target has been
   reconnected. The thread-id reflects a context that represents all
   cores on the target. Some commands may not be applicable with this
   thread-id.

   Target Disonnected Event

=disconnected,thread-id="1"

   The connection plugin has lost the connection to the target possibly
   by an explicit command. The thread-id in the event message is stale
   and should no longer be used in commands.

References

   Visible links
   1. file://localhost/home/pawel/presentations/Overview%20of%20DFW%20extensions%20to%20GDB_MI.html#TargetsInfoNode
   2. file://localhost/home/pawel/presentations/Overview%20of%20DFW%20extensions%20to%20GDB_MI.html#CoreInfoNode
   3. file://localhost/home/pawel/presentations/Overview%20of%20DFW%20extensions%20to%20GDB_MI.html#TargetsInfoNode
   4. file://localhost/home/pawel/doc/dfw/gdbmiclient/html/EventTargetConnection.html#EventTargetConnection
   5. file://localhost/home/pawel/doc/dfw/gdbmiclient/html/EventTargetStateChange.html#EventTargetStateChange
   6. file://localhost/home/pawel/doc/dfw/gdbmiclient/html/group_PrelimTargetConnectionControlBasic.html#WRSTargetConnect
   7. file://localhost/home/pawel/doc/dfw/gdbmiclient/html/group_PrelimTargetConnectionControlBasic.html#PrelimTargetSelect
   8. file://localhost/home/pawel/doc/dfw/gdbmiclient/html/group_OCDTargetPlugin.html#OCDConnectString
   9. file://localhost/home/pawel/doc/dfw/gdbmiclient/html/group_PrelimTargetConnectionControlBasic.html#PrelimTargetSelect
  10. file://localhost/home/pawel/doc/dfw/gdbmiclient/html/group_PrelimTargetConnectionControlBasic.html#WRSTargetConnect
  11. file://localhost/home/pawel/doc/dfw/gdbmiclient/html/group_PrelimTargetConnectionControlBasic.html#WRSTargetDisconnect

   Hidden links:
  12. file://localhost/home/pawel/doc/dfw/gdbmiclient/html/group_OCDTargetPlugin.html#OCDConnectString