VSCode Target-Software Debugging

README.md

@@ -150,6 +150,12 @@ The VCML documentation can be found
 
 ----
 
+## Target-Software-Debugging Tutorial
+
+You can find a tutorial that shows how to debug the executed target software using Visual Studio Code [here](vscode/).
+
+----
+
 ## License
 
 This project is licensed under the MIT license - see the

vscode/README.md

@@ -0,0 +1,69 @@
+# Visual Studio Code (VSCode) Integration
+
+## Setup
+
+1. Install the needed tools
+
+    Ubuntu:
+
+    ```bash
+    sudo apt update
+    sudo apt install gdb-multiarch git cmake build-essential lldb         # development tools
+    sudo apt install libelf-dev libsdl2-dev libvncserver-dev libslirp-dev # dependencies
+    ```
+
+1. Run the [setup script](setup.bash) to fetch the compiled Linux kernel from [avp64_sw](https://github.com/aut0/avp64_sw) and the source files for debugging
+
+    ```bash
+    <avp64 root>/vscode/setup.bash
+    ```
+1. Install the VSCode extensions
+
+    * In the end of the setup script, VSCode opens
+    * Import the [avp64.code-profile](avp64.code-profile) by following the instructions [here](https://code.visualstudio.com/docs/editor/profiles#_import). This install the required extensions
+
+1. Configure the project
+
+    * Press <kbd>F1</kbd> and type _CMake: Configure_
+    * Select the C++ compiler
+
+1. Build the project
+
+    * Press <kbd>F1</kbd> and type _CMake: Build_
+
+1. Install the project
+
+    * The project is configured to be installed at `<avp64 root>/build/{debug|release}/`. (This setting can be changed in the [\<avp64 root\>/.vscode/settings.json](../.vscode/settings.json) file)
+    * To install the project, press <kbd>F1</kbd> and type _CMake: Install_
+
+
+## Start AVP64
+
+1. Open the Debug view (<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>)
+1. At the top, after the green arrow, select _Debug AVP64_
+1. Press the green arrow to start AVP64
+1. Change to the terminal window (<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>`</kbd>) to see the the output of avp64.
+    The VP waits for a debugger to connect.
+    Sample output:
+
+    ```text
+            SystemC 2.3.3-MachineWare GmbH --- Nov 10 2023 18:03:26
+            Copyright (c) 1996-2018 by all Contributors,
+            ALL RIGHTS RESERVED
+    [I 0.000000000] system.term0: listening on port 52010
+    [I 0.000000000] system.term1: listening on port 52011
+    [I 0.000000000] system.term2: listening on port 52012
+    [I 0.000000000] system.term3: listening on port 52013
+    [D 0.001000000] created slirp ipv4 network 10.0.0.0/24
+    [D 0.001000000] created slirp ipv6 network fec0::
+    [I 0.132000000] system: starting infinite simulation using 100 us quantum
+    [I 0.138000000] system.arm0: waiting for GDB connection on port 52100
+    ```
+
+1. Connect the debugger by going back to the Debug view (<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>)
+1. At the top, after the green arrow, select _Debug Target SW_
+1. Press the green arrow to connect the debugger
+1. You can control the target using the control panel at the top.
+    You can use the dropdown menu to switch between debugging avp64 and the target software.
+
+    <img src="assets/control_panel.png" width="400">

vscode/avp64.code-profile

@@ -0,0 +1 @@
+{"name":"avp64","icon":"rocket","extensions":"[{\"identifier\":{\"id\":\"lanza.lldb-vscode\",\"uuid\":\"3890bd17-0b66-493e-a6f8-31ea9977082d\"},\"displayName\":\"LLDB VSCode\"},{\"identifier\":{\"id\":\"llvm-vs-code-extensions.vscode-clangd\",\"uuid\":\"103154cb-b81d-4e1b-8281-c5f4fa563d37\"},\"displayName\":\"clangd\"},{\"identifier\":{\"id\":\"ms-vscode.cmake-tools\",\"uuid\":\"7c889349-8749-43d4-8b5e-08939936d7f4\"},\"displayName\":\"CMake Tools\"},{\"identifier\":{\"id\":\"twxs.cmake\",\"uuid\":\"2be7cf14-2603-402e-9771-fd79df83cdf8\"},\"displayName\":\"CMake\"},{\"identifier\":{\"id\":\"webfreak.debug\",\"uuid\":\"2fd22b8e-b3b8-4e7f-9a28-a5e2d1bdd0d4\"},\"displayName\":\"Native Debug\"}]"}

vscode/launch.json

@@ -0,0 +1,38 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "lldb",
+            "request": "launch",
+            "name": "Debug AVP64",
+            "program": "${workspaceFolder}/build/debug/bin/avp64",
+            "args": [
+                "-f", "config/arm64_linux_4_19_4-x1.cfg", // the config file that should be used by avp64
+                "-c", "system.arm.gdb_wait=true" // wait until the target software debugger is connected
+            ],
+            "cwd": "${workspaceFolder}/build/debug",
+            "env": {
+                "LD_LIBRARY_PATH": "${workspaceFolder}/build/debug/lib"
+            },
+            "postRunCommands": [
+                "process handle -n true -p true -s false SIGSEGV"
+            ]
+        },
+        {
+            "type": "gdb",
+            "request": "attach",
+            "name": "Debug Target SW",
+            "gdbpath": "/usr/bin/gdb-multiarch",
+            "target": ":52100", // gdb port of avp64 that should be used (default value for cpu0)
+            "remote": true,
+            "printCalls": true,
+            "cwd": "${workspaceFolder}/build/debug/sw/arm64/linux/linux-4.19.4",
+            "valuesFormatting": "parseText",
+            "executable": "${workspaceFolder}/build/debug/sw/arm64/linux/vmlinux-4.19.4", // elf file of the software that is executed
+            "pathSubstitutions": {
+                "/app/build/buildroot/output/linux/build/linux-4.19.4": "${workspaceFolder}/build/debug/sw/arm64/linux/linux-4.19.4"
+            },
+            "stopAtConnect": true
+        }
+    ]
+}

vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "cmake.buildDirectory": "${workspaceFolder}/build/${variant:buildType}/build",
+    "cmake.installPrefix": "${workspaceFolder}/build/${variant:buildType}",
+    "cmake.copyCompileCommands": "${workspaceFolder}/compile_commands.json",
+    "cmake.generator": "Unix Makefiles",
+    "cmake.exportCompileCommandsFile": true
+}

vscode/setup.bash

@@ -0,0 +1,61 @@
+#!/bin/env bash
+
+##############################################################################
+#                                                                            #
+# Copyright 2023 Nils Bosbach                                                #
+#                                                                            #
+# This software is licensed under the MIT license.                           #
+# A copy of the license can be found in the LICENSE file at the root         #
+# of the source tree.                                                        #
+#                                                                            #
+##############################################################################
+
+
+# Get directory of script itself
+SOURCE="${BASH_SOURCE[0]}"
+# resolve $SOURCE until the file is no longer a symlink
+while [ -h "$SOURCE" ]; do
+        DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+        SOURCE="$(readlink "$SOURCE")"
+        # if $SOURCE was a relative symlink, we need to resolve it relative to the
+        # path where the symlink file was located
+        [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+
+LINUX_SW=https://github.com/aut0/avp64_sw/releases/latest/download/linux.tar.gz
+LINUX_SRC=https://mirrors.edge.kernel.org/pub/linux/kernel/v4.x/linux-4.19.4.tar.gz
+LINUX_ARCHIVE="${LINUX_SRC##*/}"
+LINUX_DIRNAME="${LINUX_ARCHIVE%.tar.gz}"
+ROOT_DIR=${DIR}/..
+VSCODE_DIR=${ROOT_DIR}/.vscode
+EXTENSIONS=(llvm-vs-code-extensions.vscode-clangd twxs.cmake ms-vscode.cmake-tools vadimcn.vscode-lldb webfreak.debug)
+
+# fetch linux
+wget ${LINUX_SW}
+tar -xvf linux.tar.gz
+rm linux.tar.gz
+
+# copy sw folder
+mkdir -p ${ROOT_DIR}/build/{debug,release}
+mv sw ${ROOT_DIR}/build/debug
+ln -s -r ${ROOT_DIR}/build/debug/sw ${ROOT_DIR}/build/release/sw
+
+# get linux sources
+wget ${LINUX_SRC}
+tar -xf ${LINUX_ARCHIVE}
+rm ${LINUX_ARCHIVE}
+mv ${LINUX_DIRNAME} ${ROOT_DIR}/build/release/sw/arm64/linux/
+
+# setup .vscode folder
+mkdir ${ROOT_DIR}/.vscode
+cp ${DIR}/settings.json ${VSCODE_DIR}/
+cp ${DIR}/launch.json ${VSCODE_DIR}/
+
+# apply patches
+pushd ${ROOT_DIR}/deps/ocx-qemu-arm/unicorn > /dev/null
+git apply ${ROOT_DIR}/patches/unicorn-*.patch
+popd > /dev/null
+
+# open VS Code
+code ${ROOT_DIR}