Multi core debugging

Multi-core debugging

WORK IN PROGRESS -- We are currently updating VSCode to add better multi-core debugging which includes handling multiple debug sessions in one instance of VSCode. Multiple sessions can be independent of multi-core but from a look and feel the feel similar. Multiple sessions can be used using a Launch Group or Compound Launch and they can work. There are a couple of issues with debugging the type of targets we deal with

• All launches are done near simultaneously. Usually, there is a dependency and no dependency can be enforced (not easily anyway)
• Information may need to be passed between instances about TCP ports to connect to, etc.
• Synchronized Restart/Reset cannot be done

We will address some of these issues using Chained Configurations. The theory is as follows. You will need a primary configuration (launch or attach type) that will start the GDB Server (OpenOCD, STLink-GdbServer, pyocd, JLinkGDBServer, etc.). The first instance in most cases (except JLink) creates TCP ports for multiple debuggers (gdb) to connect to; one for each processor core. In the case of JLink, one server is launched for each processor core. The primary configuration can optionally launch additional configurations. In launch.json, it can look something like

    // What follows is a proposal. Not the FINAL incarnation
    "numberOfProcessors": 3,
    "targetProcessor": 1,
    "chainedConfigurations": {
        "enabled": true,
        "waitOnEvent": "postInit",
        "lifeCycleShared": true,
        "launches": [                               // Array of launches. Order is respected
            {
                "name": "Attach Network Core",     // Name of another configuration
                "folder": "${workspaceRoot}/../net"
            }
        ]
    }

Most of the properties are available at the top level and for each launch. When specified at the top level, they are inherited by all the launches and each launch item can override the group. There is nothing stops a child configuration from having its own chained configurations. Hence the term chained.

Configurations are organized as a tree with the primary configuration at the root. They are typically related in some way. The child launches do not even have to be cortex-debug configurations. Thay can be any valid configuration specified in launch.json

Configuration properties

Name	Type	Description
enabled	boolean	At the top level, disables all chained configurations. You can enable at the top level but disable it for a chained launch individually
waitOnEvent	enum	"postStart"
name	string	Exact name of the launch configuration. See folder below.
folder	string	Default: "". If not specified or an empty string, it means the current folder but it can be another folder in the workspace. You can either use the full-path name or the simple base-name of the folder as it appears in the .code-workspace file. Case matters.
delayMs	number	Number of milliseconds to wait to launch this configuration. There is naturally a 5-millisecond delay between launches but you can add to that. The delays are additive in the chain.
detached	boolean	If 'true' means that the chained launch configuration will have its own server and not shared with the parent. This is typical for 'JLink' gdbservers. For servers like OpenOCD, pyOCD, STLink-GdbServer, this should be false especially for multi-core devices. Unless specified, this is automatically done for you.
lifeCycleShared	boolean	See #Life cycle management section below
launches	array	Array of launch objects where each launch object describes a chained launch. Applies to top-level only.

Life cycle management

This affects actions like Restart, Reset, Stop and Disconnect. While we decide what to do, you can submit your suggestions at https://github.com/Marus/cortex-debug/issues/547