User:Iguessthislldo/libx86emu
Difficulty level |
---|
Advanced |
libx86emu is a C library for emulating a real mode or a limited protected mode x86 CPU. Like Virtual 8086 Mode, it can be used to call BIOS functions, such as the ones for using VBE, without dropping back into real mode. Unlike virtual 8086 mode though, it can be used in protected mode and long mode. It might also be preferred because it doesn't require as much low level integration with the OS as the virtual 8086 mode does. It was created by the SciTech Software Inc. in the 1990's. It was integrated into the XFree86 server, which was later forked to create the X.org server. In addition to the fork that still exists in X.org, there is a separate fork on GitHub that is maintained as part of OpenSUSE Linux.
While it's possible to use the libx86emu found in X.org, this article will assume the OpenSUSE fork is being used, specifically version 3.1. It will also assume the library is going to be integrated into the kernel and the source code of the library isn't going to be modified.
Dependencies
The following C headers and definitions are required to build:
stdio.h
- Can include the
stddef.h
freestanding header to getsize_t
. int vsnprintf(char* buffer, size_t bufsz, const char* format, va_list vlist
- This can be a stub implementation, but is needed for logging to be fully functional.
- Can include the
stdlib.h
- Can include the
stddef.h
freestanding header to getNULL
andsize_t
. void* malloc(size_t size)
void* calloc(size_t num, size_t size)
void free(void* ptr)
- Can include the
string.h
char* strcat(char* dest, const char* src);
- This can be a stub implementation, but is needed for logging to be fully functional.
sys
io.h
- These could be stubs depending on how emulation is setup to perform port I/O.
unsigned char inb(unsigned short int port)
unsigned short int inw(unsigned short int port)
unsigned int inl(unsigned short int port)
void outb(unsigned char value, unsigned short int port)
void outw(unsigned short int value, unsigned short int port)
void outl(unsigned int value, unsigned short int port)
time.h
time_t
time_t time(time_t* arg)
- This can be a stub implementation, only needed to use the
X86EMU_RUN_TIMEOUT
flag to limit the time a emulation runs.
- This can be a stub implementation, only needed to use the
Building
All the C files in the root of the source tree are part of the library and should be built together with the headers outlined above. One thing to note is that the undefined behavior sanitizer (UBsan), which is the -fsanitize=undefined
option in Clang and GCC, should be not be used with libx86emu because some of the emulated instructions might set it off during execution.
Building with the Zig Build System
If using the Zig build system to build the library, it always passes -fsanitize=undefined
for C code in a debug mode, so it will need to be disabled. It can be disabled by passing -fsanitize-blacklist=BLACKLIST_FILE
to the C compile options, where BLACKLIST_FILE
is a path to a file relative to the Zig build file. This file should contain something like:
[undefined] src:*/libx86emu/*
This assumes the C files are in a directory called libx86emu
.
Example Usage
TODO