Visual Studio Code

This is a guide to setup your Visual Studio Code project with debugging support on both real hardware using dcload-ip and with the lxdream-nitro emulator.

Prerequisites

To start with, this tutorial makes the following assumptions:

• You have already installed and set up your KallistiOS development environment

1. if you want to be able to debug, be sure to compile gdb as specified on that page

• You have already downloaded and installed Visual Studio Code (version 1.78.2 was used for this tutorial)

VSCode Setup

• Launch Visual Studio Code
• (optional but recommended) To keep your configuration settings, plugins, ... specific to Dreamcast projects only:

1. Create a "Profile" (Menu: File-Preferences-Profiles) called "Dreamcast"

• (required) Install the following extensions: (Menu: View-Extensions)

1. C/C++ from Microsoft
2. Makefile Tools from Microsoft

Setup per Project

Compilation

(all the following steps happen in Visual Studio Code)

1. Open the folder containing your project (Menu: File-Open Folder... eg: /opt/toolchains/dc/kos/examples/dreamcast/2ndmix)
2. (if you are using Profiles) Make sure that the "Dreamcast" profile is selected (Menu: File-Preferences-Profiles)
3. Create a new subfolder ".vscode"
4. insert the following files in the ".vscode" subfolder:

• settings.json

{
    "makefile.alwaysPreConfigure": true,
    "makefile.preConfigureScript": ".vscode/kos_environ.sh",
    "makefile.makePath": "make"
}

• kos_environ.sh

#!/bin/bash

#set the KOS environtment variables
source /opt/toolchains/dc/kos/environ.sh

• c_cpp_properties.json

{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                "${workspaceFolder}/**",
                "/opt/toolchains/dc/kos/include",
                "/opt/toolchains/dc/kos/kernel/arch/dreamcast/include",
                "/opt/toolchains/dc/kos/addons/include",
                "/opt/toolchains/dc/kos-ports/include"
            ],
            "defines": [
                "_arch_dreamcast"
            ],
            "compilerPath": "/opt/toolchains/dc/sh-elf/bin/sh-elf-gcc",
            "cStandard": "c11",
            "cppStandard": "c++17",
            "intelliSenseMode": "${default}",
        }
    ],
    "version": 4
}

Debugging

• Make sure that you compiled gdb for the Dreamcast, ie /opt/toolchains/dc/sh-elf/bin/sh-elf-gdb should exist (cfr prerequisites)
• Debugging in Visual Studio Code is configured in a .vscode/launch.json file. You can add as many debugging configurations as you want inside that launch.json file.

TODO

With a real Dreamcast

• Typically, one of the following tools is used to send a program to a Dreamcast:

1. via an ethernet cable & a Broadband or LAN adapter: dcload-ip
2. via a serial cable & the serial port of the Dreamcast: dcload-serial

• Make sure that the KOS_LOADER variable in /opt/toolchains/dc/kos/environ.sh is configured correctly:

1. for dcload-ip (example if the IP of the Dreamcast is 192.168.0.2):

export KOS_LOADER="dc-tool-ip -g -t 192.168.0.2 -x"

1. for dcload-serial (example if the Dreamcast is on serial port /dev/ttyS0):

export KOS_LOADER="dc-tool-ser -g -t /dev/ttyS0 -x"

• TODO: add launch.json

With an emulator

• TODO

Setup Build Tasks (Optional)

This is an option step as you are able to just specify and launch ELFs. Setting up a build task in VSCode will allow your code to rebuild before launching the debug session.

Use the following template to create your own .vscode/tasks.json file:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build",
            "type": "shell",
            "command": "make",
            "args": [
                "all"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
        },
    ]
}

Setup lxdream-nitro Launch Task

Setup a launch configuration for lxdream-nitro in your .vscode/launch.json file:

{
    "version": "0.2.0",
    "configurations": [
         {
            // display name
            "name": "LXDream",
            "type": "cppdbg",
            "request": "launch",
            // match build task name in tasks.json
            "preLaunchTask": "Build",
            "cwd": "${workspaceRoot}",
            // path to elf
            "program": "${workspaceRoot}/hello.elf",
            // path to gdb
            "miDebuggerPath": "PATH_TO_GDB",
            "setupCommands": [{
                "text": "set architecture sh",
                "description": "Set GDB Arch to SuperH",
                "ignoreFailures" : false,
            }],
            "miDebuggerServerAddress": ":9999",
            // path to lxdream-nitro
            "debugServerPath": "PATH_TO_LXDREAM",
            // lxdream-nitro flags
            "debugServerArgs": "--log=DEBUG --gdb-sh4=9999 -A null -e ${workspaceRoot}/hello.elf -n",
            "filterStdout": true,
            "filterStderr": true,
            "externalConsole": false,
            // run on connect
            "stopAtConnect": false,
            // stop at main
            "stopAtEntry": true,
            "launchCompleteCommand": "exec-run",
            "serverStarted": "SH4 GDB server running on port",
            "useExtendedRemote": true
        },
    ]
}