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"

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

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

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": "",

    "makefile.alwaysPreConfigure": true,
    "makefile.preConfigureScript": ".vscode/kos_environ.sh",
    "makefile.makePath": "make",
    
    "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 - "Makefile: Build the current target", 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 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.200):

export KOS_LOADER="dc-tool-ip -t 192.168.1.200 -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:

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

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

• launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "BBA_LAN",
            "type": "cppdbg",
            "request": "launch",
            "preLaunchTask": "Build",
            "program": "${workspaceFolder}/${fileBasenameNoExtension}.elf",
            "cwd": ".",
            "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.200 -x ${workspaceFolder}/${fileBasenameNoExtension}.elf",
            "filterStdout": false, // (default=true)
            "logging": { //Optional flags to determine what types of messages should be logged to the Debug Console.
                "exceptions": true,     //exception messages
                "moduleLoad": true,     //module load events
                "programOutput": true,  //program output
                "engineLogging": true,  //diagnostic engine logs
                "trace": false,         //diagnostic adapter command tracing 
                "traceResponse": true   //diagnostic adapter command and response tracing
            }
        },
        {
            "name": "SERIAL",
            "type": "cppdbg",
            "request": "launch",
            "preLaunchTask": "Build",
            "program": "${workspaceFolder}/${fileBasenameNoExtension}.elf",
            "cwd": ".",
            "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}/${fileBasenameNoExtension}.elf",
            "filterStdout": false, // (default=true)
            "logging": { //Optional flags to determine what types of messages should be logged to the Debug Console.
                "exceptions": true,     //exception messages
                "moduleLoad": true,     //module load events
                "programOutput": true,  //program output
                "engineLogging": true,  //diagnostic engine logs
                "trace": false,         //diagnostic adapter command tracing 
                "traceResponse": true   //diagnostic adapter command and response tracing
            }
        },
        {
            "name": "LXDream",
            "type": "cppdbg",
            "request": "launch",
            "preLaunchTask": "Build",
            "cwd": "${workspaceRoot}",
            "program": "${workspaceRoot}/hello.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}/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
        }
    ]
}

With a real Dreamcast

• TODO: 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 gdb_init

With an emulator

• TODO: explain the steps