logo3

bochscpu-python

Bindings Python pour le BochsCPU d'@yrp, utilisant la FFI pour émuler facilement et avec précision du code x86.

Installation

bochscpu-python requiert uniquement un environnement Python 3.8 ou plus récent.

Via PyPI (recommandé)

De loin le moyen le plus simple de démarrer est d'utiliser la version stable empaquetée sur PyPI.

python -m pip install bochscpu-python

Via les builds générés

Téléchargez le dernier artefact fonctionnel depuis l'onglet Github Actions du dépôt. Extrayez le fichier ZIP, puis installez le fichier .whl situé dans le dossier wheel.

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

Depuis le dépôt source

Assez simple :

python -m pip install .

Ou sans cloner :

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

Notez que cette approche nécessitera d'avoir installé tous les outils de compilation nécessaires (comme décrit ci-dessous).

Compilation

Prérequis

Python 3.8+ (avec kit de développement)
cmake
pip
un compilateur compatible C++20 (testé avec cl sous Windows, clang++ sous MacOS et g++ sous Linux)

Étapes

Compilez BochsCPU, BochsCPU-FFI, et BochsCPU-Build en suivant les instructions sur leurs pages respectives
... Sinon, les fichiers objets des bibliothèques BochsCPU-FFI pour Windows et Linux peuvent être téléchargés depuis les Github Actions build
Placez les *.lib dans bochscpu/lib/<BuildType> (où BuildType peut être Debug, Release, RelWithDebInfo, etc.)
Installez les dépendances : python -m pip install -r requirements.txt
Compilez avec cmake Cela générera le fichier bochscpu pyd (et son PDB) que vous pouvez importer depuis une session Python avec import bochscpu.
... Sinon, vous pouvez également générer un .whl depuis la racine du projet :

python -m pip wheel .

Utilisation

Importez simplement le module bochscpu et que l'aventure commence ! L'installation du paquet installera également des fichiers d'interface, permettant aux IDE modernes (VSCode, PyCharm, etc.) de proposer de l'autocomplétion utile.

Un gabarit très rudimentaire peut être réalisé comme suit :

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,])

Cela créera une session bochscpu, définira l'état du CPU en mode réel, et pré-remplira les hooks avec des callbacks de base (qui ne font qu'un print à l'exécution). Notez que cet exemple ne fera en réalité rien, car nous n'avons pas alloué de pages de code ni défini correctement les registres pour y pointer.

Un gabarit plus complet se trouve dans le dossier examples/.