Visual Studio Code

This is a guide to setup your Visual Studio Code project with debugging support on both on a real Dreamcast and with an 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"

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

1. Required:
   1. C/C++ from Microsoft
2. Optional:
   1. TODO: add useful extensions
3. (Not recommended at this moment:)
   1. (Makefile Tools from Microsoft: the current version (June 2023) is not really adapted for remote debugging)

Setup per Project

Compilation

Preparation

(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:

• kos_environ.sh

#!/bin/bash

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

• settings.json

{
    "C_Cpp.default.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"
    ],
    "C_Cpp.default.defines": [
            "_arch_dreamcast"
    ],
    "C_Cpp.default.compilerPath": "/opt/toolchains/dc/sh-elf/bin/sh-elf-gcc",
    "C_Cpp.default.cStandard": "c11",
    "C_Cpp.default.cppStandard": "c++17",
    "C_Cpp.default.intelliSenseMode": "",

    "terminal.integrated.profiles.linux": {
        "kos-bash": {
            "path": "/usr/bin/bash",
            "args": ["--init-file", "${workspaceFolder}/.vscode/kos_environ.sh" ],
            "overrideName": true
        }
    }
}

The result should look like this: TODO: replace image without c_cpp_properties.json

At this point, you should be able to compile applications for the Dreamcast!

Compilation

You can compile via 2 ways:

1. via the VSCode Command Palette - "Tasks: Run Build Task", or
2. by opening a "kos-bash" terminal (Menu: View-Terminal if not visible yet, then click on the "+" to see the terminals to choose from, and select "kos-bash"), and typing "make"

In both cases, the compilation should generate an executable file, ending with .elf

Note: "kos-bash" is a bash shell with the "source /opt/toolchains/dc/kos/environ.sh" already executed for you, so that you can run all Kallistios commands.

Running a program

For this, we will use the "make run" command that you can find in many (all?) Makefiles of the KallistiOs project, to send and run the program on 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 (BBA) or LAN adapter: dcload-ip
2. via a coder's 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.1.210):

export KOS_LOADER="dc-tool-ip -t 192.168.1.210 -x"

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

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

• Power on your dreamcast, with the dcload disc
• Open a "kos-bash" terminal, and type: make run
• The program will be running on your Dreamcast!
• (If you ran the 2ndmix example, you can press the START button on the Dreamcast pad to exit)

Debugging

Preparation

• 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, eg 1 for debugging on a dreamcast, 1 for debugging on an emulator, ...

1. insert the following files in the ".vscode" subfolder:

• kos_make.sh

#!/bin/bash

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

make

exit

• tasks.json (This makes sure that the code is compiled before launching the debug session)

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build",
            "type": "process",
            "command": "bash",
            "args": [
                "--init-file", "${workspaceFolder}/.vscode/kos_make.sh"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
        },
    ]
}

• launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "BBA_LAN",
            "type": "cppdbg",
            "request": "launch",
            "preLaunchTask": "Build",
            "cwd": "${workspaceFolder}",
            "program": "${workspaceFolder}/${workspaceFolderBasename}.elf",
            //"program": "${workspaceFolder}/2ndmix.elf",
            "MIMode": "gdb",
            "miDebuggerPath": "/opt/toolchains/dc/sh-elf/bin/sh-elf-gdb",
            "miDebuggerServerAddress":"localhost:2159",//common misconception: we connect to the gdb server offered by dc-tool-ip, NOT to the Dreamcast directly !
            "debugServerPath":"/opt/toolchains/dc/bin/dc-tool-ip",
            "debugServerArgs": "-g -t 192.168.1.210 -x ${workspaceFolder}/${workspaceFolderBasename}.elf",
            //"debugServerArgs": "-g -t 192.168.1.210 -x ${workspaceFolder}/2ndmix.elf",
            //"stopAtEntry": true,
            "externalConsole": false,
            "avoidWindowsConsoleRedirection": false,
            "internalConsoleOptions": "openOnSessionStart",
        },
        {
            "name": "SERIAL",
            "type": "cppdbg",
            "request": "launch",
            "preLaunchTask": "Build",
            "cwd": "${workspaceFolder}",
            "program": "${workspaceFolder}/${workspaceFolderBasename}.elf",
            //"program": "${workspaceFolder}/2ndmix.elf",
            "MIMode": "gdb",
            "miDebuggerPath": "/opt/toolchains/dc/sh-elf/bin/sh-elf-gdb",
            "miDebuggerServerAddress":"localhost:2159",//common misconception: we connect to the gdb server offered by dc-tool-ser, NOT to the Dreamcast directly !
            "debugServerPath":"/opt/toolchains/dc/bin/dc-tool-ser",
            "debugServerArgs": "-g -t /dev/ttyS0 -x ${workspaceFolder}/${workspaceFolderBasename}.elf",
            //"debugServerArgs": "-g -t /dev/ttyS0 -x ${workspaceFolder}/2ndmix.elf",
            //"stopAtEntry": true,
            "externalConsole": false,
            "avoidWindowsConsoleRedirection": false,
            "internalConsoleOptions": "openOnSessionStart",
        },
        {
            "name": "LXDream",
            "type": "cppdbg",
            "request": "launch",
            "preLaunchTask": "Build",
            "cwd": "${workspaceRoot}",
            "program": "${workspaceFolder}/${workspaceFolderBasename}.elf",
            //"program": "${workspaceFolder}/2ndmix.elf",
            "miDebuggerPath": "/opt/toolchains/dc/sh-elf/bin/sh-elf-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}/${workspaceFolderBasename}.elf -n",
            //"debugServerArgs": "--log=DEBUG --gdb-sh4=9999 -A null -e ${workspaceRoot}/2ndmix.elf -n",
            "filterStdout": true,
            "filterStderr": true,
            // run on connect
            "stopAtConnect": false,
            // stop at main
            "stopAtEntry": true,
            "externalConsole": false,
            "avoidWindowsConsoleRedirection": false,
            "internalConsoleOptions": "openOnSessionStart",
            "launchCompleteCommand": "exec-run",
            "serverStarted": "SH4 GDB server running on port",
            "useExtendedRemote": true
        }
    ]
}

Note that for the 3 launch configurations above, you have 2 lines for "program" and "debugServerArgs", one of which is commented out. ${workspaceFolderBasename} is the name of your project directory (eg: 2ndmix), and if that matches the name of your target .elf file (eg: 2ndmix.elf), then you can use ${workspaceFolderBasename}. If not, you can just use the other line by replacing ${workspaceFolderBasename} with the real .elf filename.

Launching a Debug session

• YTODO: explain the steps
• TODO: add gdb_init(); with breakpoint, and conditional include ?
• TODO: be sure to recompile after adding gdb_init
• TODO: be sure to not put breakpoint before or on gdb_init();, it really should only be placed after that

With an emulator

• TODO: explain the steps