IBM z/TPF Debugger
This extension provides the capabilities required to debug z/TPF programs on a remote system using the GDB debugger.
Features
The extension contributes the ztpf debugger configuration, which registers debug hooks on the z/TPF runtime. When the hooks are activated, the GDB debugger is started on the remote system using a configuration generated by this extension. The registration configuration is created in the launch.json file as documented for Visual Studio Code. Snippets for basic configurations are available. Schema validation and descriptions of each property are built-in to the extension.
Requirements
The C/C++ extension from Microsoft (ms-vscode.cpptools) is listed as a dependency for this extension. The Microsoft extension provides the foundational GDB debug adapter with support for SSH-based pipe transport to run the GDB debugger on a Linux on IBM Z system.
An SSH client must be installed and configured on the local workstation with a public/private key pair for authentication to the Linux on IBM Z system.
A GDB client must be installed on the Linux on IBM Z system.
The debugger server for GDB feature (APAR PJ48312) must be installed and running on the z/TPF runtime.
The following extension settings must be provided by the user:
- IBM z/TPF Debugger > Pipe > Program (
ztpf-debugger.pipe.program)
- IBM z/TPF Debugger > Pipe > User (
ztpf-debugger.pipe.user)
- IBM z/TPF Debugger > Pipe > Host (
ztpf-debugger.pipe.host)
- IBM z/TPF Debugger > TPFGDB > Path (
ztpf-debugger.tpfgdb.path)
- IBM z/TPF Debugger > TPFGDB > Python Path (
ztpf-debugger.tpfgdb.pythonPath)
Shared Object / Source Lookup Configuration
The values sharedObjectSearchPath and sourceFileMap in the ztpf debugger configuration are used to configure the GDB debugger on the remote system.
Shared Object Search Path
The sharedObjectSearchPath value is a JSON array and must include the absolute remote paths for all build artifacts that you wish to debug. If build output is directed to /my/remote/build/output on the Linux on IBM Z system, then the value of sharedObjectSearchPath should include /my/remote/build/output. The list is searched sequentially and the returned result is used as the target for the remote GDB process.
"sharedObjectSearchPath" : [
"/my/remote/build/output",
"<additional remote paths to search>"
]
Source File Map
The sourceFileMap value maps source paths recorded in the debug information for shared objects found through sharedObjectSearchPath to the corresponding files in the Visual Studio Code workspace. The sourceFileMap value is a JSON object in which each property key is part of a remote source path used to compile a portion of a shared object, and each property value is the corresponding workspace path. In the example configuration, if the source path recorded in the shared object is /my/remote/build/input/base/rt/qzz5.c, the matching local file path is /my/local/files/base/rt/qzz5.c.
"sourceFileMap": {
"/my/remote/build/input": "/my/local/files",
"/some/other/code": "/my/local/files"
}
TLS
Transport Layer Security (TLS) is enabled by default for ztpf debugger configurations in launch.json.
The secure parameter in the launch configuration toggles TLS: true explicitly enables TLS (the default), and false disables it.
The verifyHost parameter in the launch configuration determines whether the Linux on IBM Z system performs hostname verification of the server certificate. The default value is true which means that the hostname in the server certificate must match the hostname of the server. Setting the value to false disables hostname verification.
The remoteCAPath parameter in the launch configuration specifies the remote path to a Certificate Authority (CA) certificate file. When this parameter is set, the remote GDB process on Linux on IBM Z will use this certificate file for TLS. Otherwise, the remote GDB process uses the remote system's default CA certificates for TLS.
The ztpf-debugger.TLS.serverCertificate extension setting specifies the path to a Certificate Authority (CA) certificate file on the workstation. When this setting is configured, the certificate at the provided path is appended to the default set of trusted certificates used by the Node.js runtime when communicating using the HTTPS protocol. Otherwise, the default set of trusted certificates is used.
Known Limitations
This extension currently only supports registering by program name and debugging C/C++ programs.
Providing multiple entries in the sourceFileMap value may cause breakpoints to not be activated, particularly if the source file that includes the breakpoint can be mapped to multiple locations.
The LICENSE file is included in the extension for license information.
