use argh::{FromArgValue, FromArgs};
use crate::{
dbg_backend::DebugBackend,
diagnostics,
error::{Error, Result},
gdb::GdbClient,
kd::KdBackend,
memory_backend::MemoryBackend,
repl::start_repl,
session, symbols, virsh,
};
#[cfg(feature = "mcp")]
use crate::mcp;
#[derive(Clone, Copy, PartialEq, Eq)]
enum BackendKind {
Gdb,
Kd,
Memory,
}
impl FromArgValue for BackendKind {
fn from_arg_value(value: &str) -> std::result::Result<Self, String> {
match value {
"gdb" => Ok(BackendKind::Gdb),
"kd" => Ok(BackendKind::Kd),
"memory" => Ok(BackendKind::Memory),
other => Err(format!(
"unknown backend '{other}': expected 'kd', 'gdb', or 'memory'"
)),
}
}
}
#[derive(FromArgs)]
struct Args {
#[argh(switch, short = 'v', long = "version")]
version: bool,
#[argh(switch, long = "force-download-symbols")]
redownload_symbols: bool,
#[argh(switch, long = "gdbstub-instructions")]
gdbstub_instructions: bool,
#[argh(switch, long = "kd-instructions")]
kd_instructions: bool,
#[argh(option, short = 'b', long = "backend", default = "BackendKind::Kd")]
backend: BackendKind,
#[argh(option, long = "connect")]
connect: Option<String>,
#[argh(subcommand)]
command: Option<Command>,
}
#[derive(FromArgs)]
#[argh(subcommand)]
enum Command {
Virsh(VirshCommand),
#[cfg(feature = "mcp")]
Mcp(McpCommand),
}
#[cfg(feature = "mcp")]
#[derive(FromArgs)]
#[argh(subcommand, name = "mcp")]
struct McpCommand {
#[argh(option, long = "http")]
http: Option<String>,
#[argh(switch, long = "unsafe-http")]
unsafe_http: bool,
}
#[derive(FromArgs)]
#[argh(subcommand, name = "virsh")]
struct VirshCommand {}
static GDBSTUB_INSTRUCTIONS: &str = "The gdb backend talks to QEMU's gdbstub instead of Windows KD.
It does not require Windows debug mode, but it loses Windows-native
KD behavior such as bugcheck debug text and KD reboot signalling.
To enable it, pass the following arguments to QEMU:
-s -S
Then run ntoseye with:
ntoseye --backend gdb
If you are running QEMU via commandline, simply append the arguments
to your existing command.
If you are running QEMU via virt-manager, you must edit the libvirt
XML file, which can be done through their GUI. Once there, add:
<domain xmlns:qemu=\"http://libvirt.org/schemas/domain/qemu/1.0\" type=\"kvm\">
...
<qemu:commandline>
<qemu:arg value=\"-s\"/>
<qemu:arg value=\"-S\"/>
</qemu:commandline>
</domain>";
static KD_INSTRUCTIONS: &str = "The KD backend is ntoseye's default backend.
It speaks the same wire protocol WinDbg uses, over a serial pipe
between QEMU and ntoseye. It requires Windows to be booted in debug
mode (which removes the 'stealth' property of the gdb backend:
anti-debug code, PatchGuard, and even some Windows behaviors change
when /debug is on).
GUEST: enable kernel debugging over a serial port (run as
Administrator, then reboot):
bcdedit /debug on
bcdedit /dbgsettings serial debugport:1 baudrate:115200
If your hypervisor wires the KD serial as COM2 (see the libvirt
note below), use 'debugport:2' instead.
QEMU (commandline): route COM1 to a host-side Unix socket. The
path here matches ntoseye's default; adjust both sides if you pick
a different one:
-chardev socket,id=kd,path=/tmp/ntoseye-kd.sock,server=on,wait=off -serial chardev:kd
QEMU via virt-manager / libvirt: virt-manager auto-adds a <serial>
console device on every VM, and it claims COM1. Either replace or
remove that device so the KD chardev becomes COM1 (recommended), or
leave it in place and the KD chardev will be COM2 (use 'debugport:2'
in bcdedit instead of 'debugport:1').
OPTION A (recommended): replace the auto-added <serial> with one
that points at our Unix socket. KD is COM1, 'debugport:1' is correct.
<serial type=\"unix\">
<source mode=\"bind\" path=\"/tmp/ntoseye-kd.sock\"/>
<target type=\"isa-serial\" port=\"0\"/>
</serial>
OPTION B: leave the auto-added serial alone and append the KD
chardev via qemu:commandline. KD ends up as COM2, so use
'debugport:2' in bcdedit.
<domain xmlns:qemu=\"http://libvirt.org/schemas/domain/qemu/1.0\" type=\"kvm\">
...
<qemu:commandline>
<qemu:arg value=\"-chardev\"/>
<qemu:arg value=\"socket,id=kd,path=/tmp/ntoseye-kd.sock,server=on,wait=off\"/>
<qemu:arg value=\"-serial\"/>
<qemu:arg value=\"chardev:kd\"/>
</qemu:commandline>
</domain>
Once the guest is booting (or already booted and waiting for the
debugger), run:
ntoseye --connect /tmp/ntoseye-kd.sock
ntoseye waits 8 seconds for the initial KD handshake by default.
For unusually slow guests, override it with:
NTOSEYE_KD_TIMEOUT=20 ntoseye";
pub fn main() {
if let Err(e) = run() {
diagnostics::print_error(e);
std::process::exit(1);
}
}
fn run() -> Result<()> {
let args: Args = argh::from_env();
if args.version {
println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
return Ok(());
}
if args.gdbstub_instructions {
println!("{}", GDBSTUB_INSTRUCTIONS);
return Ok(());
}
if args.kd_instructions {
println!("{}", KD_INSTRUCTIONS);
return Ok(());
}
symbols::FORCE_DOWNLOADS
.set(args.redownload_symbols)
.map_err(|_| {
Error::DebugInfo("symbol download flag was initialized before startup".into())
})?;
if let Some(command) = args.command {
return match command {
Command::Virsh(_) => virsh::run_interactive(),
#[cfg(feature = "mcp")]
Command::Mcp(mcp_args) => {
let backend = match args.backend {
BackendKind::Gdb => "gdb",
BackendKind::Kd => "kd",
BackendKind::Memory => "memory",
};
mcp::run(
backend.to_string(),
args.connect.clone(),
mcp_args.http.clone(),
mcp_args.unsafe_http,
)
.map_err(|e| Error::DebugInfo(e.to_string()))
}
};
}
let mut ctx = session::Session::connect(|| -> Result<Box<dyn DebugBackend>> {
Ok(match args.backend {
BackendKind::Gdb => {
let addr = args.connect.as_deref().unwrap_or("127.0.0.1:1234");
Box::new(GdbClient::connect(addr)?)
}
BackendKind::Kd => {
let path = args.connect.as_deref().unwrap_or("/tmp/ntoseye-kd.sock");
Box::new(KdBackend::connect(path)?)
}
BackendKind::Memory => {
if args.connect.is_some() {
return Err(Error::DebugInfo(
"memory backend does not use --connect".to_string(),
));
}
Box::new(MemoryBackend::new())
}
})
})?;
start_repl(&mut ctx)
}