From 84407e70cf819a49a2ee7a25a4b20db19a31f650 Mon Sep 17 00:00:00 2001 From: Chris Pick Date: Fri, 25 Apr 2025 18:39:28 -0400 Subject: [PATCH] Add notes on using crate from Linux userspace It took me a little research to figure out how to use this crate from x86/x86_64 Linux userspace. Add some notes to help people in the future. --- README.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b63bae7..9339d1a 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,8 @@ Add the special ISA debug exit device by passing the flags: -device isa-debug-exit,iobase=0xf4,iosize=0x04 ``` -When instantiating the handle, `iobase` must be given as the first parameter. +When instantiating the handle with `qemu_exit::X86::new()`, `iobase` must be given as the first +parameter. The second parameter must be an `EXIT_SUCCESS` code of your choice that is an odd number, aka bit number zero must be `1`. This is needed because in QEMU, the provided code is internally @@ -69,6 +70,18 @@ possible to let QEMU invoke `exit(0)`. let qemu_exit_handle = qemu_exit::X86::new(io_base, custom_exit_success); ``` +#### x86/x86_64 Linux + +To use this mechanism from Linux userspace, the kernel must be compiled with +`CONFIG_X86_IOPL_IOPERM=y` (which is the default) and the process must start with root privileges +(or `CAP_SYS_RAWIO`) and call: [`ioperm(2)`](https://man7.org/linux/man-pages/man2/ioperm.2.html): +```rust +nix::errno::Errno::result(unsafe { libc::ioperm( 0xf4, 4, 1 )}).expect("ioperm failed"); +``` + +Privileges/capabilities can then be dropped. Normal users can subsequently call +`qemu_exit_handle.exit*()`. + ## Literature - [Semihosting for AArch32 and AArch64](https://github.com/ARM-software/abi-aa/blob/main/semihosting/semihosting.rst)