Json Debug Interface (JDI)

JDI (pronounced "Jay-Dai") is a Dolwin service and debugging interface that connects all the emulator components through a single hub.

The following entities are included in the JDI infrastructure:

Json description of component debugging commands (JDI Node)
Implementation of debugging commands (encapsulated inside the component)
The common hub (JDI Hub) through which the execution of commands is performed

The main idea is to isolate the internal state of the emulator components, with the ability to access them using Json.

Each component implements a separate JDI Node. All JDI Nodes are accessible through a single hub (Debug::Hub).

Json JDI Node format

Json consists of two main sections: info and can.

Section info

Contains a description of the JDI Node (description) and the helpGroup header, which is shown in the help command when listing the commands for this JDI Node.

Section can

The can section contains a description of what this JDI Node can do.

The section contains entries with descriptions of debug commands. Important properties:

help: description of the command for help called by the help command
hints: additional hints that are displayed opposite the command
args: number of required arguments (not counting args[0])
usage: detailed help for the command if it was called with insufficient arguments
output: an informative hint in case the command returns some data in the form of Json::Value
internal: the command is not displayed in the help list. Internal use.

All properties except the help property are optional.

Debug commands

The debug command callback (delegate) procedure is as follows:


typedef Json::Value* (*CmdDelegate)(std::vector<std::string>& args);

The command accepts a list of arguments. The args[0] argument contains the name of the command itself.

The command may return some Json::Value or nullptr.

The return value must be deleted after use (delete).

Commands do not need to check the number of arguments. This task is performed by the JDI Hub (using the "args" property).

Command example:

	// Mount GC DVD image (GCM)
	static Json::Value* MountIso(std::vector<std::string>& args)
	{
		bool result = MountFile(args[1]);

		if (result)
		{
			DBReport2(DbgChannel::DVD, "Mounted disk image: %s\n", args[1].c_str());
		}
		else
		{
			DBReport2(DbgChannel::Error, "Failed to mount disk image: %s\n", args[1].c_str());
		}

		Json::Value* output = new Json::Value();
		output->type = Json::ValueType::Bool;
		output->value.AsBool = result;

		return output;
	}

Debug output

Commands can output textual debugging information using the classic DBReport and DBReport2 methods.

DBReport outputs information to a common channel. DBReport2 outputs information to the specified channel. The list of available channels (DbgChannel) is in the Debugger.h header.

Reflector

A special method that registers the association of a debug command with its text name.

Reflector is used only once when adding JDI Node.

Reflector example:

	void DvdCommandsReflector()
	{
		Debug::Hub.AddCmd("DvdInfo", DvdInfo);
		Debug::Hub.AddCmd("MountIso", MountIso);
		Debug::Hub.AddCmd("OpenLid", OpenLid);
		Debug::Hub.AddCmd("CloseLid", CloseLid);
		Debug::Hub.AddCmd("DvdStats", DvdStats);
		Debug::Hub.AddCmd("MountSDK", MountSDK);
		Debug::Hub.AddCmd("UnmountDvd", UnmountDvd);
		Debug::Hub.AddCmd("DvdSeek", DvdSeek);
		Debug::Hub.AddCmd("DvdRead", DvdRead);
		Debug::Hub.AddCmd("DvdOpenFile", DvdOpenFile);
	}

Adding JDI Node

Create Json Description
Make a .cpp module with command implementation and reflector
Call Debug::Hub::AddNode

Execution of commands

The method Debug::Hub::Execute is used.

3.8 KiB Raw Permalink Blame History