logo3

bochscpu-python

Python-Bindings für @yrps BochsCPU unter Verwendung von FFI, um x86-Code einfach und präzise zu emulieren.

Install

bochscpu-python erfordert lediglich eine Python-Umgebung ab Version 3.8.

Über PyPI (bevorzugt)

Der mit Abstand einfachste Weg, alles zum Laufen zu bringen, ist die Verwendung der stabilen Paketversion auf PyPI

python -m pip install bochscpu-python

Über die generierten Builds

Lade das neueste funktionierende Artefakt vom GitHub-Actions-Tab des Repositorys herunter. Entpacke die ZIP-Datei und installiere die .whl-Datei, die du im Ordner wheel findest.

python -m pip install wheel/bochscpu-$version-$os-$arch.whl

Aus dem Quell-Repository

Ziemlich unkompliziert:

python -m pip install .

Oder ohne Klonen:

python -m pip install git+https://github.com/hugsy/bochscpu-python.git#egg=bochscpu-python

Beachte, dass für diesen Ansatz alle erforderlichen Build-Tools installiert sein müssen (wie unten beschrieben).

Build

Voraussetzungen

Python 3.8+ (mit Entwicklungskit)
cmake
pip
einen C++20-kompatiblen Compiler (getestet mit cl für Windows, clang++ für macOS und g++ für Linux)

Schritte

Erstelle BochsCPU, BochsCPU-FFI und BochsCPU-Build gemäß den Anweisungen auf den jeweiligen Seiten
... Alternativ können die Objektdateien der BochsCPU-FFI-Bibliotheken für Windows & Linux vom build GitHub Actions heruntergeladen werden
Verschiebe die *.lib-Dateien in bochscpu/lib/<BuildType> (wobei BuildType Debug, Release, RelWithDebInfo usw. sein kann)
Installiere die Abhängigkeiten: python -m pip install -r requirements.txt
Erstelle mit cmake Dadurch wird die bochscpu-pyd-Datei (und ihre PDB) erzeugt, die du aus einer Python-Sitzung mit import bochscpu importieren kannst.
... Alternativ kannst du auch ein .whl aus dem Projektstammverzeichnis erzeugen:

python -m pip wheel .

Verwendung

Importiere einfach das Modul bochscpu und der Spaß kann beginnen! Beim Installieren des Pakets werden auch Schnittstellendateien installiert, sodass moderne IDEs (VSCode, PyCharm usw.) nützliche Vervollständigung anbieten können.

Ein sehr einfaches Grundgerüst kann wie folgt erstellt werden:

import bochscpu, bochscpu.utils, bochscpu.cpu

sess = bochscpu.Session()
sess.missing_page_handler = bochscpu.utils.callbacks.missing_page_cb
state = bochscpu.State()
bochscpu.cpu.set_real_mode(state)
hook = bochscpu.Hook()
bochscpu.utils.callbacks.install_default_callbacks(hook)
sess.run([hook,])

Dadurch wird eine bochscpu-Sitzung erstellt, der CPU-Zustand für den Real Mode festgelegt und Hooks mit einfachen Callbacks vorbelegt (die bei der Ausführung lediglich ein print ausführen). Beachte, dass dieses Beispiel tatsächlich nichts tun wird, da wir keine Codepages alloziert und die Register nicht korrekt darauf gesetzt haben.

Eine vollständigere Vorlage findest du im examples/-Ordner.