{"id":16712859,"url":"https://github.com/hugsy/bochscpu-python","last_synced_at":"2025-04-09T17:21:29.756Z","repository":{"id":188411786,"uuid":"677112739","full_name":"hugsy/bochscpu-python","owner":"hugsy","description":"Python bindings for BochsCPU","archived":false,"fork":false,"pushed_at":"2025-02-26T04:17:37.000Z","size":146,"stargazers_count":35,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-02T14:13:44.048Z","etag":null,"topics":["assembly","bochs","bochscpu","emulation","python3","x86","x86-64"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hugsy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-10T19:12:01.000Z","updated_at":"2025-02-23T22:06:06.000Z","dependencies_parsed_at":"2023-12-16T05:33:46.926Z","dependency_job_id":"19845a5a-780b-4d5b-b19f-7b60e0372f02","html_url":"https://github.com/hugsy/bochscpu-python","commit_stats":null,"previous_names":["hugsy/bochscpu-python"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hugsy%2Fbochscpu-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hugsy%2Fbochscpu-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hugsy%2Fbochscpu-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hugsy%2Fbochscpu-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hugsy","download_url":"https://codeload.github.com/hugsy/bochscpu-python/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248075005,"owners_count":21043510,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembly","bochs","bochscpu","emulation","python3","x86","x86-64"],"created_at":"2024-10-12T20:44:20.357Z","updated_at":"2025-04-09T17:21:29.734Z","avatar_url":"https://github.com/hugsy.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n   \u003cimg alt=\"logo3\" src=\"https://github.com/hugsy/bochscpu-python/assets/590234/decb861d-8d2e-46b5-ae7e-5fc90d4fc98f\"  width=\"250px\"/\u003e \n\u003c/p\u003e\n\n# bochscpu-python\n\n[![Python 3.8+](https://img.shields.io/pypi/v/bochscpu-python.svg)](https://pypi.org/project/bochscpu-python/)\n[![Downloads](https://static.pepy.tech/badge/bochscpu-python)](https://pepy.tech/project/bochscpu-python)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Licence MIT](https://img.shields.io/packagist/l/doctrine/orm.svg?maxAge=2592000?style=plastic)](https://github.com/hugsy/bochscpu-python/blob/main/LICENSE)\n[![Builds](https://github.com/hugsy/bochscpu-python/actions/workflows/build.yml/badge.svg)](https://github.com/hugsy/bochscpu-python/actions/workflows/build.yml)\n\nPython bindings for [@yrp](https://github.com/yrp604/)'s [BochsCPU](https://github.com/yrp604/bochscpu) using [FFI](https://github.com/yrp604/bochscpu-ffi) to easily and accurately emulate x86 code.\n\n\n## Install\n\n`bochscpu-python` requires a Python environment of 3.8 or more recent only.\n\n### Via PyPI (preferred)\n\nBy far the simplest way to get things up and running is using the [stable packaged version](https://pypi.org/project/bochscpu-python/) on [PyPI](https://pypi.org/)\n\n```bash\npython -m pip install bochscpu-python\n```\n\n\n### Via the generated builds\n\nDownload the latest working artifact from [the repository Github Actions tab](https://github.com/hugsy/bochscpu-python/actions). Extract the ZIP file, install the `.whl` file you'll find inside the `wheel` folder.\n\n```bash\npython -m pip install wheel/bochscpu-$version-$os-$arch.whl\n```\n\n### From the source repository\n\nFairly straight forward:\n\n```bash\npython -m pip install .\n```\n\nOr without cloning\n\n```bash\npython -m pip install git+https://github.com/hugsy/bochscpu-python.git#egg=bochscpu-python\n```\n\nNote that this approach will require you to have all the building tools necessary installed (as described below)\n\n## Build\n\n### Requirements\n\n * Python 3.8+ (with development kit)\n * `cmake`\n * `pip`\n * a C++20 compatible compiler (tested `cl` for Windows, `clang++` for MacOS and `g++` Linux)\n\n### Steps\n\n * Build BochsCPU, BochsCPU-FFI, and BochsCPU-Build following the instructions on their respective pages\n * ... Alternatively BochsCPU-FFI for Windows \u0026 Linux libraries object files can be downloaded from the [`build` Github Actions](https://github.com/hugsy/bochscpu-python/actions/workflows/build.yml?query=branch%3Amain+is%3Asuccess+event%3Apush)\n * Move the `*.lib` in `bochscpu/lib/\u003cBuildType\u003e` (where `BuildType` can be `Debug`, `Release`, `RelWithDebInfo`, etc.)\n * Install the requirements: `python -m pip install -r requirements.txt`\n * Build with `cmake`\n   This will generate the bochscpu `pyd` file (and its PDB) which you can import from a Python session with `import bochscpu`.\n * ... Alternatively you can also generate a `.whl` from the root of the project:\n\n```bash\npython -m pip wheel .\n```\n\n## Usage\n\n\nJust import the `bochscpu` module and let the fun begin! Installing the package will also install interface files, allowing modern IDEs (VSCode, PyCharm, etc.) to offer useful completion.\n\nA very crude template can be made as such:\n\n```python\nimport bochscpu, bochscpu.utils, bochscpu.cpu\n\nsess = bochscpu.Session()\nsess.missing_page_handler = bochscpu.utils.callbacks.missing_page_cb\nstate = bochscpu.State()\nbochscpu.cpu.set_real_mode(state)\nhook = bochscpu.Hook()\nbochscpu.utils.callbacks.install_default_callbacks(hook)\nsess.run([hook,])\n```\n\nThis will create a bochscpu session, set the CPU state for real mode, and pre-populate hooks with basic callbacks (that only perform a `print` upon execution). Note that this sample will actually do nothing as we haven't allocated code pages nor correctly set registers to point to it. \n\nA more complete template can be found in the [`examples/` folder](https://github.com/hugsy/bochscpu-python/blob/main/examples/template.py)\n\n\n## Some Examples\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\nEmulate a Fibonascii sequence in x64 long mode\n\u003c/summary\u003e\n\n\n\n\nhttps://github.com/hugsy/bochscpu-python/assets/590234/adc5ac5a-a8eb-4982-9537-5ece3f32f8f8\n\n\n[Code](examples/long_mode_fibonacci.py)\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\nEmulate code from a Windows 11 x64 memory dump\n\u003c/summary\u003e\n\n![image](https://github.com/hugsy/bochscpu-python/assets/590234/2ea77b17-cf59-4ec3-a38b-602d63e201f8)\n\n[Code](examples/long_mode_emulate_windows_kdump.py)\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003e\nEmulate a \u003ccode\u003eprint(\"hello world\")\u003c/code\u003e-like assembly code in 16 bit real mode\n\u003c/summary\u003e\n\n\nhttps://github.com/hugsy/bochscpu-python/assets/590234/eb06af06-4b10-490e-ae40-a1d0aed333ca\n\n\n[Code](examples/real_mode_print_hello_world.py)\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\nEmulate Linux Glibc's \u003ccode\u003erand()\u003c/code\u003e function on x64\n\u003c/summary\u003e\n\n\nhttps://github.com/hugsy/bochscpu-python/assets/590234/2486adbc-0878-46f5-83ed-3bcf9774fd26\n\n\n[Code](examples/long_mode_emulate_linux_udump.py)\n\n\u003c/details\u003e\n\n## Enjoy 🍻\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhugsy%2Fbochscpu-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhugsy%2Fbochscpu-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhugsy%2Fbochscpu-python/lists"}