libx86emu

https://github.com/wfeldt/libx86emu
Admin
A small library to emulate x86 instructions with hooks for memory access, I/O, interrupts, and...
Tokens:8,064
Snippets:73
Trust Score:7.2
Update:5 months ago
Show doc for...
Tokens:
Raw
### x86emu_run

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Starts the emulation process. It can be controlled by flags such as timeout or maximum instructions.

```APIDOC
## x86emu_run

### Description
Start emulation

### Signature
```c
unsigned x86emu_run(x86emu_t *emu, unsigned flags);
```

### Parameters
* `emu` (x86emu_t *) - Pointer to the emulation object.
* `flags` (unsigned) - Control flags for emulation:
    * `X86EMU_RUN_TIMEOUT`: Set `emu->timeout` to max. seconds to run.
    * `X86EMU_RUN_MAX_INSTR`: Set `emu->max_instr` to max. instructions to emulate.
    * `X86EMU_RUN_NO_EXEC`: No execution flag.
    * `X86EMU_RUN_NO_CODE`: No code flag.
    * `X86EMU_RUN_LOOP`: Loop flag.

### Returns
* `unsigned` - Indicates why `x86emu_run()` stopped (corresponds to flags).
```

--------------------------------

### Start Emulation

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Begins the x86 instruction emulation process. The emulation can be controlled by flags such as timeout or maximum instructions. The return value indicates the reason for stopping.

```c
unsigned x86emu_run(x86emu_t *emu, unsigned flags);
```

--------------------------------

### Set Memory/IO Access Handler with x86emu_set_memio_handler

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Installs a custom handler for all memory and I/O accesses. The handler receives the address, a pointer to the value, and the access type. It should return the old handler.

```c
typedef unsigned (* x86emu_memio_handler_t)(x86emu_t *emu, u32 addr, u32 *val, unsigned type);
x86emu_memio_handler_t x86emu_set_memio_handler(x86emu_t *emu, x86emu_memio_handler_t handler);
```

--------------------------------

### Set Code Execution Handler with x86emu_set_code_handler

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Installs a callback function to be executed before each instruction is decoded. If the handler returns non-zero, emulation stops. Logging may already be enabled.

```c
typedef int (* x86emu_code_handler_t)(x86emu_t *emu);
x86emu_code_handler_t x86emu_set_code_handler(x86emu_t *emu, x86emu_code_handler_t handler);
```

--------------------------------

### Set CPUID Handler with x86emu_set_cpuid_handler

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Installs a callback function to handle the CPUID instruction. This allows for custom CPU emulation or using the host's CPUID. Without a handler, a #UD exception occurs.

```c
typedef void (* x86emu_cpuid_handler_t)(x86emu_t *emu);
x86emu_cpuid_handler_t x86emu_set_cpuid_handler(x86emu_t *emu, x86emu_cpuid_handler_t handler);
```

--------------------------------

### x86emu_set_intr_handler

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Sets a callback function to handle interrupts. The handler is invoked at the start of interrupt processing and can either complete the handling or let the emulator proceed.

```APIDOC
## x86emu_set_intr_handler

### Description
Sets an interrupt handler that is called at the beginning of the interrupt handling procedure.

### Signature
```c
x86emu_intr_handler_t x86emu_set_intr_handler(x86emu_t *emu, x86emu_intr_handler_t handler);
```

### Parameters
- **emu** (*x86emu_t* *) - Pointer to the emulator context.
- **handler** (x86emu_intr_handler_t) - The callback function to set. This function should have the signature `int (*)(x86emu_t *emu, u8 num, unsigned type)`.

### Return Value
Returns the previously set interrupt handler.

### Notes
The `type` parameter can be `INTR_TYPE_SOFT` or `INTR_TYPE_FAULT`, and can be bitmasked with `INTR_MODE_RESTART` and `INTR_MODE_ERRCODE`.
If the handler returns 1, interrupt handling is considered complete, and the emulator skips its own processing. If it returns 0, the emulator continues with normal interrupt processing.
```

--------------------------------

### Set Interrupt Handler with x86emu_set_intr_handler

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Registers a custom interrupt handler. The handler is invoked at the start of interrupt processing. Returning 1 signifies completion, allowing the emulator to skip its default handling; returning 0 continues normal processing.

```c
typedef int (* x86emu_intr_handler_t)(x86emu_t *emu, u8 num, unsigned type);
x86emu_intr_handler_t x86emu_set_intr_handler(x86emu_t *emu, x86emu_intr_handler_t handler);
```

--------------------------------

### Create New Emulation Object

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Initializes a new x86 emulation object with default memory and I/O permissions. Remember to free the object later using x86emu_done().

```c
x86emu_t *x86emu_new(unsigned def_mem_perm, unsigned def_io_perm);
```

--------------------------------

### x86emu_new

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Creates a new emulation object with specified default memory and I/O permissions. Use x86emu_done() to free the object later.

```APIDOC
## x86emu_new

### Description
Create new emulation object

### Signature
```c
x86emu_t *x86emu_new(unsigned def_mem_perm, unsigned def_io_perm);
```

### Parameters
* `def_mem_perm` (unsigned) - Default permissions for memory accesses.
* `def_io_perm` (unsigned) - Default permissions for I/O accesses.

### Returns
* `x86emu_t *` - A pointer to the newly created emulation object.
```

--------------------------------

### x86emu_set_log

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Sets up a log buffer for the emulator. If the buffer becomes full, a provided flush function is called. The buffer is freed when x86emu_done() is called. The buffer size must be larger than 1024 bytes.

```APIDOC
## x86emu_set_log

### Description
Set log buffer

### Signature
```c
void x86emu_set_log(x86emu_t *emu, char *buffer, unsigned buffer_size, x86emu_flush_func_t flush);

typedef void (* x86emu_flush_func_t)(x86emu_t *emu, char *buf, unsigned size);
```

### Parameters
* `emu` (x86emu_t *) - Pointer to the emulation object.
* `buffer` (char *) - Pointer to the log buffer.
* `buffer_size` (unsigned) - The size of the log buffer (must be > 1024 bytes).
* `flush` (x86emu_flush_func_t) - A function pointer to call when the buffer is full. Can be NULL.
```

--------------------------------

### x86emu_clone

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Creates a copy of an existing emulation object. The copy should be freed later using x86emu_done().

```APIDOC
## x86emu_clone

### Description
Clone emulation object

### Signature
```c
x86emu_t *x86emu_clone(x86emu_t *emu);
```

### Parameters
* `emu` (x86emu_t *) - Pointer to the emulation object to clone.

### Returns
* `x86emu_t *` - A pointer to the newly created copy of the emulation object.
```

--------------------------------

### Map Memory Area with x86emu_set_page

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Maps a memory area of X86EMU_PAGE_SIZE into the emulator at a specified offset. The offset must be page-aligned. Use NULL for address to switch back to emulated memory. Memory permissions are still enforced.

```c
void x86emu_set_page(x86emu_t *emu, unsigned offset, void *address);
```

--------------------------------

### x86emu_set_page

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Maps a memory area of X86EMU_PAGE_SIZE into the emulator at a specified offset. Memory permissions are still enforced. If the address is NULL, it switches back to emulated memory.

```APIDOC
## x86emu_set_page

### Description
Direct memory access function to map a memory area into the emulator.

### Signature
```c
void x86emu_set_page(x86emu_t *emu, unsigned offset, void *address);
```

### Parameters
- **emu** (*x86emu_t* *) - Pointer to the emulator context.
- **offset** (unsigned) - The offset within the emulator's memory space where the mapping should occur. Must be `X86EMU_PAGE_SIZE` aligned.
- **address** (void *) - The host memory address to map. If NULL, switches back to emulated memory.

### Notes
Memory permissions still apply and can be managed via `x86emu_set_perm()`.
```

--------------------------------

### x86emu_dump

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Dumps the current state of the emulator to the log buffer based on the provided flags.

```APIDOC
## x86emu_dump

### Description
Dump emulator state

### Signature
```c
void x86emu_dump(x86emu_t *emu, int flags);
```

### Parameters
* `emu` (x86emu_t *) - Pointer to the emulation object.
* `flags` (int) - Bitmask of flags to determine what state to dump:
    * `X86EMU_DUMP_REGS`: Dump registers.
    * `X86EMU_DUMP_MEM`: Dump memory.
    * `X86EMU_DUMP_ACC_MEM`: Dump accessed memory.
    * `X86EMU_DUMP_INV_MEM`: Dump invalid memory accesses.
    * `X86EMU_DUMP_ATTR`: Dump attributes.
    * `X86EMU_DUMP_ASCII`: Dump in ASCII format.
    * `X86EMU_DUMP_IO`: Dump I/O ports.
    * `X86EMU_DUMP_INTS`: Dump interrupts.
    * `X86EMU_DUMP_TIME`: Dump timing information.
```

--------------------------------

### Set I/O Permissions with x86emu_set_io_perm

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Sets I/O permissions for a specified range. Permissions are defined by x86emu_set_perm().

```c
void x86emu_set_io_perm(x86emu_t *emu, unsigned start, unsigned end, unsigned perm);
```

--------------------------------

### x86emu_log

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Writes formatted output to the emulator's log buffer. This function supports printf-style formatting.

```APIDOC
## x86emu_log

### Description
Write to log

### Signature
```c
void x86emu_log(x86emu_t *emu, const char *format, ...) __attribute__ ((format (printf, 1, 2)));
```

### Parameters
* `emu` (x86emu_t *) - Pointer to the emulation object.
* `format` (const char *) - The format string for the log message.
* `...` - Additional arguments for the format string.
```

--------------------------------

### Clone Emulation Object

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Creates a duplicate of an existing emulation object. The returned copy must be freed using x86emu_done().

```c
x86emu_t *x86emu_clone(x86emu_t *emu);
```

--------------------------------

### Set Log Buffer

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Configures a buffer for logging emulation events. A flush function can be provided to handle buffer overflows. The buffer is managed by the emulator and freed in x86emu_done(). The buffer must be larger than 1024 bytes.

```c
void x86emu_set_log(x86emu_t *emu, char *buffer, unsigned buffer_size, x86emu_flush_func_t flush);
```

```c
typedef void (* x86emu_flush_func_t)(x86emu_t *emu, char *buf, unsigned size);
```

--------------------------------

### Set WRMSR Handler with x86emu_set_wrmsr_handler

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Sets an alternative callback function for the WRMSR instruction. This allows for custom MSR emulation. The default handler modifies the 'msr' and 'msr_perm' arrays in x86emu_t.

```c
typedef void (* x86emu_wrmsr_handler_t)(struct x86emu_s *);
x86emu_wrmsr_handler_t x86emu_set_wrmsr_handler(x86emu_t *emu, x86emu_wrmsr_handler_t handler);
```

--------------------------------

### x86emu_set_code_handler

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Sets a callback function that is executed before each instruction is decoded and emulated. The handler can stop emulation by returning a non-zero value.

```APIDOC
## x86emu_set_code_handler

### Description
Sets an execution hook that is called before a new instruction is decoded and emulated.

### Signature
```c
x86emu_code_handler_t x86emu_set_code_handler(x86emu_t *emu, x86emu_code_handler_t handler);
```

### Parameters
- **emu** (*x86emu_t* *) - Pointer to the emulator context.
- **handler** (x86emu_code_handler_t) - The callback function to set. This function should have the signature `int (*)(x86emu_t *emu)`.

### Return Value
Returns the previously set code handler.

### Notes
If the handler returns a value not equal to 0, the emulation is stopped.
```

--------------------------------

### x86emu_set_io_perm

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Sets I/O permissions for a specified range. Permissions are defined by constants similar to memory permissions.

```APIDOC
## x86emu_set_io_perm

### Description
Sets I/O permissions for a specified range of I/O ports.

### Signature
```c
void x86emu_set_io_perm(x86emu_t *emu, unsigned start, unsigned end, unsigned perm);
```

### Parameters
- **emu** (*x86emu_t* *) - Pointer to the emulator context.
- **start** (unsigned) - The starting I/O port address.
- **end** (unsigned) - The ending I/O port address.
- **perm** (unsigned) - The permissions to set. See `x86emu_set_perm()` for details on permission constants.
```

--------------------------------

### x86emu_set_perm

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Sets memory permissions for a specified range. Permissions include read, write, execute, and access tracking.

```APIDOC
## x86emu_set_perm

### Description
Memory permissions

### Signature
```c
void x86emu_set_perm(x86emu_t *emu, unsigned start, unsigned end, unsigned perm);
```

### Parameters
* `emu` (x86emu_t *) - Pointer to the emulation object.
* `start` (unsigned) - The starting address of the memory range.
* `end` (unsigned) - The ending address of the memory range.
* `perm` (unsigned) - A bitmask of permissions:
    * `X86EMU_PERM_R`: Memory is readable.
    * `X86EMU_PERM_W`: Memory is writable.
    * `X86EMU_PERM_X`: Memory is executable.
    * `X86EMU_PERM_VALID`: Memory has been initialized.
    * `X86EMU_ACC_R`: Memory has been read.
    * `X86EMU_ACC_W`: Memory has been written.
    * `X86EMU_ACC_X`: Memory has been executed.
    * `X86EMU_ACC_INVALID`: An invalid access occurred.
```

--------------------------------

### x86emu_set_memio_handler

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Sets an alternative callback function to handle all memory and I/O accesses. The handler is invoked for read, write, and execute operations on memory, as well as I/O port accesses.

```APIDOC
## x86emu_set_memio_handler

### Description
Sets an alternative callback function to handle memory and I/O accesses.

### Signature
```c
x86emu_memio_handler_t x86emu_set_memio_handler(x86emu_t *emu, x86emu_memio_handler_t handler);
```

### Parameters
- **emu** (*x86emu_t* *) - Pointer to the emulator context.
- **handler** (x86emu_memio_handler_t) - The callback function to set. This function should have the signature `unsigned (*)(x86emu_t *emu, u32 addr, u32 *val, unsigned type)`.

### Return Value
Returns the previously set memory/IO handler.

### Notes
The `type` parameter is a combination of memory access size (e.g., `X86EMU_MEMIO_8`, `X86EMU_MEMIO_16`, `X86EMU_MEMIO_32`, `X86EMU_MEMIO_8_NOPERM`) and operation type (e.g., `X86EMU_MEMIO_R` for read, `X86EMU_MEMIO_W` for write, `X86EMU_MEMIO_X` for execute, `X86EMU_MEMIO_I` for I/O read, `X86EMU_MEMIO_O` for I/O write).
```

--------------------------------

### x86emu_done

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Deletes an emulation object and frees all associated memory. Returns NULL.

```APIDOC
## x86emu_done

### Description
Delete emulation object

### Signature
```c
x86emu_t *x86emu_done(x86emu_t *emu);
```

### Parameters
* `emu` (x86emu_t *) - Pointer to the emulation object to be deleted.

### Returns
* `NULL` - Always returns NULL after freeing memory.
```

--------------------------------

### Write to Log

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Writes formatted output to the emulator's log buffer. This function supports printf-style formatting.

```c
void x86emu_log(x86emu_t *emu, const char *format, ...) __attribute__ ((format (printf, 1, 2)));
```

--------------------------------

### Memory Access Functions

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Provides convenience functions for reading and writing byte, word, and dword values to and from the emulator's memory. Includes functions that bypass permission checks.

```APIDOC
## Memory Access Functions

### Description
Convenience functions for accessing emulator memory.

### Read Functions
- **x86emu_read_byte(emu, addr)**: Reads a byte from the specified address.
- **x86emu_read_byte_noperm(emu, addr)**: Reads a byte without checking permissions.
- **x86emu_read_word(emu, addr)**: Reads a word (2 bytes) from the specified address.
- **x86emu_read_dword(emu, addr)**: Reads a double word (4 bytes) from the specified address.

### Write Functions
- **x86emu_write_byte(emu, addr, val)**: Writes a byte to the specified address.
- **x86emu_write_byte_noperm(emu, addr, val)**: Writes a byte without checking permissions.
- **x86emu_write_word(emu, addr, val)**: Writes a word (2 bytes) to the specified address.
- **x86emu_write_dword(emu, addr, val)**: Writes a double word (4 bytes) to the specified address.

### Parameters
- **emu** (*x86emu_t* *) - Pointer to the emulator context.
- **addr** (unsigned) - The memory address.
- **val** (unsigned) - The value to write.

### Notes
Memory access restrictions (defined by `x86emu_set_perm()`) apply to all functions except for the `_noperm()` variants.
```

--------------------------------

### x86emu_set_wrmsr_handler

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Sets a callback function to handle the WRMSR (Write Model-Specific Register) instruction. This allows for custom MSR emulation or interaction with host MSR values.

```APIDOC
## x86emu_set_wrmsr_handler

### Description
Sets an alternative callback function to handle the WRMSR instruction.

### Signature
```c
x86emu_wrmsr_handler_t x86emu_set_wrmsr_handler(x86emu_t *emu, x86emu_wrmsr_handler_t handler);
```

### Parameters
- **emu** (*x86emu_t* *) - Pointer to the emulator context.
- **handler** (x86emu_wrmsr_handler_t) - The callback function to set. This function should have the signature `void (*)(struct x86emu_s *)`.

### Return Value
Returns the previously set WRMSR handler.

### Notes
The default callback uses the `msr` array in the `x86emu_t` structure to write MSRs and updates the `msr_perm` array. This handler allows for custom MSR emulation.
```

--------------------------------

### x86emu_intr_raise

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Raises an interrupt in the emulator. The interrupt is handled before the next instruction is executed.

```APIDOC
## x86emu_intr_raise

### Description
Raises an interrupt within the emulator.

### Signature
```c
void x86emu_intr_raise(x86emu_t *emu, u8 intr_nr, unsigned type, unsigned err);
```

### Parameters
- **emu** (*x86emu_t* *) - Pointer to the emulator context.
- **intr_nr** (u8) - The interrupt number.
- **type** (unsigned) - The type of interrupt. See `x86emu_set_intr_func()` for possible values.
- **err** (unsigned) - The error code to be pushed onto the stack if `INTR_MODE_ERRCODE` is set in the type.
```

--------------------------------

### Set Segment Register in x86emu

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Use this function to set a segment register. Ensure you have a valid `x86emu_t` and `sel_t` pointer.

```c
void x86emu_set_seg_register(x86emu_t *emu, sel_t *seg, u16 val);
R_CS_SEL, R_DS_SEL, R_ES_SEL, R_FS_SEL, R_GS_SEL, R_SS_SEL
```

```c
x86emu_set_seg_register(emu, emu->x86.R_CS_SEL, 0x7c0);
```

--------------------------------

### x86emu_reset

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Resets the CPU state of the emulator, including clearing registers and setting the code segment and instruction pointer.

```APIDOC
## x86emu_reset

### Description
Reset cpu state

### Signature
```c
void x86emu_reset(x86emu_t *emu);
```

### Parameters
* `emu` (x86emu_t *) - Pointer to the emulation object to reset.
```

--------------------------------

### Stop Emulation

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Signals the emulator to stop execution. This function is typically used within callbacks, and the emulator will return from x86emu_run() after the current instruction completes.

```c
void x86emu_stop(x86emu_t *emu);
```

--------------------------------

### Set Memory Permissions

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Defines access permissions for a specified range of memory. Permissions include read, write, execute, and validity, as well as access tracking flags.

```c
void x86emu_set_perm(x86emu_t *emu, unsigned start, unsigned end, unsigned perm);
```

--------------------------------

### Set RDMSR Handler with x86emu_set_rdmsr_handler

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Sets an alternative callback function for the RDMSR instruction. This enables custom MSR emulation. The default handler uses the 'msr' and 'msr_perm' arrays in x86emu_t.

```c
typedef void (* x86emu_rdmsr_handler_t)(struct x86emu_s *);
x86emu_rdmsr_handler_t x86emu_set_rdmsr_handler(x86emu_t *emu, x86emu_rdmsr_handler_t handler);
```

--------------------------------

### x86emu_set_cpuid_handler

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Sets a callback function to handle the CPUID instruction. This allows for custom CPU identification emulation or using the host's CPUID information.

```APIDOC
## x86emu_set_cpuid_handler

### Description
Sets a callback function to handle the CPUID instruction.

### Signature
```c
x86emu_cpuid_handler_t x86emu_set_cpuid_handler(x86emu_t *emu, x86emu_cpuid_handler_t handler);
```

### Parameters
- **emu** (*x86emu_t* *) - Pointer to the emulator context.
- **handler** (x86emu_cpuid_handler_t) - The callback function to set. This function should have the signature `void (*)(x86emu_t *emu)`.

### Return Value
Returns the previously set CPUID handler.

### Notes
If no handler is installed, the program will raise an #UD exception. There is no default implementation.
```

--------------------------------

### x86emu Debug Instruction Formats

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

These are special debug instructions interpreted by the emulator when `X86EMU_TRACE_DEBUG` is set. They allow for logging, trace flag manipulation, and state dumping.

```assembly
db 0x67, 0xeb, LEN, DATA...
```

```assembly
db 0x01
```

```assembly
db STRING
```

```assembly
db 0x02
```

```assembly
dd flags
```

```assembly
db 0x03
```

```assembly
dd flags
```

```assembly
db 0x04
```

```assembly
dd flags
```

```assembly
db 0x05
```

--------------------------------

### x86emu_clear_log

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Clears the emulator's log buffer. Optionally flushes the current log content before clearing.

```APIDOC
## x86emu_clear_log

### Description
Clear log

### Signature
```c
unsigned x86emu_clear_log(x86emu_t *emu, int flush);
```

### Parameters
* `emu` (x86emu_t *) - Pointer to the emulation object.
* `flush` (int) - If non-zero, flushes the current log content before clearing.

### Returns
* `unsigned` - The size of the log buffer.
```

--------------------------------

### x86emu_stop

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Stops the emulation. This function is typically called from within a callback (e.g., an interrupt handler) to signal the emulator to halt after the current instruction.

```APIDOC
## x86emu_stop

### Description
Stop emulation

### Signature
```c
void x86emu_stop(x86emu_t *emu);
```

### Parameters
* `emu` (x86emu_t *) - Pointer to the emulation object to stop.
```

--------------------------------

### x86emu_set_rdmsr_handler

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Sets a callback function to handle the RDMSR (Read Model-Specific Register) instruction. This enables custom MSR emulation or using host MSR values.

```APIDOC
## x86emu_set_rdmsr_handler

### Description
Sets an alternative callback function to handle the RDMSR instruction.

### Signature
```c
x86emu_rdmsr_handler_t x86emu_set_rdmsr_handler(x86emu_t *emu, x86emu_rdmsr_handler_t handler);
```

### Parameters
- **emu** (*x86emu_t* *) - Pointer to the emulator context.
- **handler** (x86emu_rdmsr_handler_t) - The callback function to set. This function should have the signature `void (*)(struct x86emu_s *)`.

### Return Value
Returns the previously set RDMSR handler.

### Notes
The default callback uses the `msr` array in the `x86emu_t` structure and updates the `msr_perm` array. This handler allows for custom MSR emulation.
```

--------------------------------

### Dump Emulator State

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Writes the current state of the emulator to the log buffer. Various flags can be used to specify which parts of the state to dump, including registers, memory, I/O, interrupts, and timing information.

```c
void x86emu_dump(x86emu_t *emu, int flags);
```

--------------------------------

### Write Word to Emulator Memory

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Writes a 16-bit word to emulator memory at the specified address. Permissions apply.

```c
void x86emu_write_word(x86emu_t *emu, unsigned addr, unsigned val);
```

--------------------------------

### Debug Instruction

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Details on the special debug instruction used for tracing and debugging the x86 emulator when the X86EMU_TRACE_DEBUG flag is set.

```APIDOC
## Debug instruction

If the `X86EMU_TRACE_DEBUG` flags is set, the emulator interprets a special debug instruction:

```assembly
db 0x67, 0xeb, LEN, DATA...
```

This is a short jump with an address size prefix. `LEN` is the size of `DATA`.

### DATA Formats:

- `db 0x01`
  Print `STRING` to log. `STRING` is not null-terminated.

- `db 0x02`
  `dd flags`
  Set trace flags.

- `db 0x03`
  `dd flags`
  Clear trace flags.

- `db 0x04`
  `dd flags`
  Dump emulator state. For flags, see `x86emu_dump()`.

- `db 0x05`
  Reset memory access stats. See `x86emu_reset_access_stats()`.
```

--------------------------------

### Write Byte to Emulator Memory

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Writes a single byte to emulator memory at the specified address. Permissions apply unless _noperm version is used.

```c
void x86emu_write_byte(x86emu_t *emu, unsigned addr, unsigned val);
```

```c
void x86emu_write_byte_noperm(x86emu_t *emu, unsigned addr, unsigned val);
```

--------------------------------

### Raise Interrupt with x86emu_intr_raise

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Forces an interrupt to be handled before the next instruction. The 'type' parameter follows x86emu_set_intr_func() definitions, and 'err' is the error code if INTR_MODE_ERRCODE is set.

```c
void x86emu_intr_raise(x86emu_t *emu, u8 intr_nr, unsigned type, unsigned err);
```

--------------------------------

### Write Double Word to Emulator Memory

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Writes a 32-bit double word to emulator memory at the specified address. Permissions apply.

```c
void x86emu_write_dword(x86emu_t *emu, unsigned addr, unsigned val);
```

--------------------------------

### Reset Memory Access Statistics with x86emu_reset_access_stats

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Resets all memory access statistics, clearing the X86EMU_ACC_* bits for the entire memory space.

```c
void x86emu_reset_access_stats(x86emu_t *emu);
```

--------------------------------

### Read Word from Emulator Memory

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Reads a 16-bit word from emulator memory at the specified address. Permissions apply.

```c
unsigned x86emu_read_word(x86emu_t *emu, unsigned addr);
```

--------------------------------

### Read Byte from Emulator Memory

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Reads a single byte from emulator memory at the specified address. Permissions apply unless _noperm version is used.

```c
unsigned x86emu_read_byte(x86emu_t *emu, unsigned addr);
```

```c
unsigned x86emu_read_byte_noperm(x86emu_t *emu, unsigned addr);
```

--------------------------------

### Clear Log Buffer

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Clears the emulator's log buffer. Optionally flushes the current log content before clearing. Returns the size of the buffer.

```c
unsigned x86emu_clear_log(x86emu_t *emu, int flush);
```

--------------------------------

### Delete Emulation Object

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Frees all memory associated with the emulation object. Returns NULL after successful deallocation.

```c
x86emu_t *x86emu_done(x86emu_t *emu);
```

--------------------------------

### Reset CPU State

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Resets the CPU state of the emulator, clearing registers and setting the code segment and instruction pointer.

```c
void x86emu_reset(x86emu_t *emu);
```

--------------------------------

### x86emu_set_seg_register

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Sets a segment register in the x86 emulator. This function allows modification of segment selectors like CS, DS, ES, FS, GS, and SS.

```APIDOC
## x86emu_set_seg_register

### Description
Set segment register

### Signature
```c
void x86emu_set_seg_register(x86emu_t *emu, sel_t *seg, u16 val);
```

### Parameters
- `emu` (*x86emu_t*): Pointer to the emulator context.
- `seg` (*sel_t*): Pointer to the segment selector to be set.
- `val` (*u16*): The new value for the segment register.

### Constants
- `R_CS_SEL`
- `R_DS_SEL`
- `R_ES_SEL`
- `R_FS_SEL`
- `R_GS_SEL`
- `R_SS_SEL

### Example
```c
x86emu_set_seg_register(emu, emu->x86.R_CS_SEL, 0x7c0);
```
```

--------------------------------

### x86emu_reset_access_stats

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Resets the memory access statistics for the entire emulator memory. This clears the X86EMU_ACC_* bits.

```APIDOC
## x86emu_reset_access_stats

### Description
Resets the memory access statistics for the entire emulator memory.

### Signature
```c
void x86emu_reset_access_stats(x86emu_t *emu);
```

### Parameters
- **emu** (*x86emu_t* *) - Pointer to the emulator context.

### Notes
This operation clears the `X86EMU_ACC_*` bits for all memory locations.
```

--------------------------------

### Read Double Word from Emulator Memory

Source: https://github.com/wfeldt/libx86emu/blob/master/README.md

Reads a 32-bit double word from emulator memory at the specified address. Permissions apply.

```c
unsigned x86emu_read_dword(x86emu_t *emu, unsigned addr);
```
Tokens:
Raw