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 get size_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.

• stdlib.h
  • Can include the stddef.h freestanding header to get NULL and size_t.
  • void* malloc(size_t size)
  • void* calloc(size_t num, size_t size)
  • void free(void* ptr)

• 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.

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 for 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 using by passing -fsanitize-blacklist=BLACKLIST_FILE, where BLACKLIST_FILE is a path to a file relative to the Zig build file. This file should contain:

 [undefined]
 src:*/libx86emu/*

This assumes the C files are in a directory called libx86emu.

Example Usage

TODO

External Links

• libx86emu on GitHub
• libx86emu in X.org server