Add exception for hlt instruction

Bump icicle version

.cargo/config.toml

@@ -0,0 +1,2 @@
+[env]
+GHIDRA_SRC = { value = "python/icicle", relative = true }

.github/workflows/CI.yml

@@ -2,160 +2,232 @@ name: CI
 
 on: [push, pull_request]
 
+# Automatically cancel previous runs of this workflow on the same branch
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
+  linux:
+    # Skip building pull requests from the same repository
+    if: ${{ github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository) }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        target: [x86_64, aarch64]
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          submodules: 'true'
+
+      - name: Update pyproject.toml version
+        if: ${{ startsWith(github.ref, 'refs/tags/') }}
+        shell: bash
+        run: |
+          # Extract version from tag (strip 'v' prefix if present)
+          VERSION=${GITHUB_REF#refs/tags/}
+          VERSION=${VERSION#v}
+          echo "Extracted version: $VERSION"
+          
+          # Update version in pyproject.toml (works on both GNU and BSD sed)
+          sed -i.bak "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
+          rm pyproject.toml.bak
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.9.3"
+
+      # NOTE: On Linux we need to manually export LD_LIBRARY_PATH
+      - name: Set up Python
+        run: |
+          uv python install --default
+          LIBDIR=$(python -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
+          echo "LD_LIBRARY_PATH=${LIBDIR}:${LD_LIBRARY_PATH}" >> $GITHUB_ENV
+
+      - name: Run Python tests
+        run: uv run pytest -v
+
+      - name: Run Rust tests
+        run: cargo run
+
+      - name: Clean Rust build cache
+        run: cargo clean
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist --find-interpreter
+          manylinux: auto
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-linux-${{ matrix.target }}
+          path: dist
+
   windows:
     # Skip building pull requests from the same repository
     if: ${{ github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository) }}
     runs-on: windows-latest
-    env:
-      # Disable output buffering in an attempt to get readable errors
-      PYTHONUNBUFFERED: '1'
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
+      - uses: actions/checkout@v5
         with:
           submodules: 'true'
-      
-      - name: Python environment
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.10'
 
-      - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@stable
-        with:
-          targets: x86_64-pc-windows-msvc
-
-      - name: Build
+      - name: Update pyproject.toml version
+        if: ${{ startsWith(github.ref, 'refs/tags/') }}
         shell: bash
         run: |
-          pip install -r requirements.txt
-          python setup.py sdist
-          python setup.py bdist_wheel --py-limited-api=cp37
-          pip install --force-reinstall dist/*.whl
-          python -c "import icicle"
+          # Extract version from tag (strip 'v' prefix if present)
+          VERSION=${GITHUB_REF#refs/tags/}
+          VERSION=${VERSION#v}
+          echo "Extracted version: $VERSION"
+          
+          # Update version in pyproject.toml (works on both GNU and BSD sed)
+          sed -i.bak "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
+          rm pyproject.toml.bak
 
-      - name: Test
-        run: |
-          pip install -r tests/requirements.txt
-          python tests/example.py
-          python tests/invalid.py
-    
-      - name: Upload wheels
-        uses: actions/upload-artifact@v3
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
         with:
-          name: wheels
+          version: "0.9.3"
+
+      - name: Set up Python
+        run: uv python install --default
+
+      - name: Run Rust tests
+        run: cargo run
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: x64
+          args: --release --out dist --find-interpreter
+
+      - name: Run Python tests
+        run: uv run pytest -v
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-windows-x64
           path: dist
 
   macos:
     # Skip building pull requests from the same repository
     if: ${{ github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository) }}
     runs-on: macos-latest
-    env:
-      # Disable output buffering in an attempt to get readable errors
-      PYTHONUNBUFFERED: '1'
+    strategy:
+      matrix:
+        target: [x86_64, aarch64]
+      fail-fast: false
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
+      - uses: actions/checkout@v5
         with:
           submodules: 'true'
-      
-      - name: Python environment
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.10'
 
-      - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@stable
-        with:
-          targets: aarch64-apple-darwin, x86_64-apple-darwin
-      
-      - name: Build
+      - name: Update pyproject.toml version
+        if: ${{ startsWith(github.ref, 'refs/tags/') }}
         shell: bash
-        env:
-          DEVELOPER_DIR: /Applications/Xcode.app/Contents/Developer
-          MACOSX_DEPLOYMENT_TARGET: '10.9'
-          ARCHFLAGS: -arch x86_64 -arch arm64
-          PYO3_CROSS_LIB_DIR: /Applications/Xcode.app/Contents/Developer/Library/Frameworks/Python3.framework/Versions/3.8/lib
         run: |
-          pip install -r requirements.txt
-          python setup.py bdist_wheel --py-limited-api=cp37
-          pip install --force-reinstall dist/*_universal2.whl
-          python -c "import icicle"
-      
-      - name: Test
-        run: |
-          pip install -r tests/requirements.txt
-          python tests/example.py
-          python tests/invalid.py
-    
-      - name: Upload wheels
-        uses: actions/upload-artifact@v3
+          # Extract version from tag (strip 'v' prefix if present)
+          VERSION=${GITHUB_REF#refs/tags/}
+          VERSION=${VERSION#v}
+          echo "Extracted version: $VERSION"
+          
+          # Update version in pyproject.toml (works on both GNU and BSD sed)
+          sed -i.bak "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
+          rm pyproject.toml.bak
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
         with:
-          name: wheels
+          version: "0.9.3"
+
+      - name: Set up Python
+        run: uv python install --default
+
+      - name: Run Rust tests
+        if: matrix.target == 'aarch64'
+        run: cargo run --release
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist --find-interpreter
+
+      - name: Run Python tests
+        if: matrix.target == 'aarch64'
+        run: uv run pytest -v
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-macos-${{ matrix.target }}
           path: dist
 
-  linux:
+  sdist:
     # Skip building pull requests from the same repository
     if: ${{ github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository) }}
     runs-on: ubuntu-latest
-    container: quay.io/pypa/manylinux2014_x86_64
-    env:
-      # Disable output buffering in an attempt to get readable errors
-      PYTHONUNBUFFERED: '1'
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
+      - uses: actions/checkout@v5
         with:
           submodules: 'true'
-      
-      - name: Build
+
+      - name: Update pyproject.toml version
+        if: ${{ startsWith(github.ref, 'refs/tags/') }}
         shell: bash
         run: |
-          curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain stable -y && yum install -y openssl-devel
-          export PATH="$PATH:$HOME/.cargo/bin"
-          export PATH="/opt/python/cp38-cp38/bin:$PATH"
-          pip install -r requirements.txt
-          python setup.py bdist_wheel --py-limited-api=cp37 --plat-name manylinux2014_x86_64
-          auditwheel show dist/*.whl
-          pip install --force-reinstall dist/*.whl
-          python -c "import icicle"
-      
-      - name: Test
-        run: |
-          export PATH="/opt/python/cp38-cp38/bin:$PATH"
-          pip install -r tests/requirements.txt
-          python tests/example.py
-          python tests/invalid.py
-    
-      - name: Upload wheels
-        uses: actions/upload-artifact@v3
+          # Extract version from tag (strip 'v' prefix if present)
+          VERSION=${GITHUB_REF#refs/tags/}
+          VERSION=${VERSION#v}
+          echo "Extracted version: $VERSION"
+          
+          # Update version in pyproject.toml (works on both GNU and BSD sed)
+          sed -i.bak "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
+          rm pyproject.toml.bak
+
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
         with:
-          name: wheels
+          command: sdist
+          args: --out dist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-sdist
           path: dist
 
   release:
     if: ${{ startsWith(github.ref, 'refs/tags/') }}
     runs-on: ubuntu-latest
-    needs: [windows, macos, linux]
+    needs: [linux, windows, macos, sdist]
     permissions:
       contents: write
       discussions: write
+      id-token: write
     steps:
       - name: Download wheels
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v5
         with:
-          name: wheels
+          pattern: wheels-*
+          merge-multiple: true
           path: dist
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@b7f401de30cb6434a1e19f805ff006643653240e # v1.8.10
+        uses: PyO3/maturin-action@v1
         with:
-          password: ${{ secrets.PYPI_API_TOKEN }}
-          packages-dir: dist/
+          command: upload
+          args: --non-interactive --skip-existing dist/*
 
       - name: Release
-        uses: softprops/action-gh-release@c9b46fe7aad9f02afd89b12450b780f52dacfb2d # master 2023-03-26
+        uses: softprops/action-gh-release@6da8fa9354ddfdc4aeace5fc48d7f679b5214090 # v2.4.1
         with:
           generate_release_notes: true
           files: dist/*

.python-version

@@ -0,0 +1 @@
+3.8

Cargo.toml

@@ -1,24 +1,26 @@
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
 [package]
 name = "icicle-python"
-version = "0.0.2"
 edition = "2021"
+rust-version = "1.90.0"
 
 [lib]
 name = "icicle"
-crate-type = ["cdylib"]
+crate-type = ["cdylib", "lib"]
+
+[[bin]]
+name = "tests"
+path = "tests.rs"
 
 [dependencies]
+pyo3 = { version = "0.27.1", features = ["indexmap", "abi3-py38"] }
 icicle-cpu = { path = "icicle-emu/icicle-cpu" }
 icicle-vm = { path = "icicle-emu/icicle-vm" }
 pcode = { path = "icicle-emu/sleigh/pcode" }
 sleigh-runtime = { path = "icicle-emu/sleigh/sleigh-runtime" }
-indexmap = "1.9.3"
-pyo3 = { version = "0.19.2", features = ["extension-module", "indexmap", "abi3-py37"] }
-target-lexicon = "0.12.7"
+indexmap = "*"
+target-lexicon = "*"
 tracing = "*"
-tracing-subscriber = "0.3.17"
+tracing-subscriber = "*"
 
 [build-dependencies]
-pyo3-build-config = "0.19.2"
+pyo3-build-config = "0.27.1"

README.md

@@ -1,32 +1,52 @@
 # icicle-python
 
-This project is an easy to use Python wrapper around [icicle-emu](https://github.com/icicle-emu/icicle-emu). You can read more about Icicle in the paper: [Icicle: A Re-designed Emulator for Grey-Box Firmware Fuzzing](https://arxiv.org/pdf/2301.13346.pdf).
+This project is an easy-to-use Python wrapper around [icicle-emu](https://github.com/icicle-emu/icicle-emu). You can read more about Icicle in the paper: [Icicle: A Re-designed Emulator for Grey-Box Firmware Fuzzing](https://arxiv.org/pdf/2301.13346.pdf).
 
 ## Installation
 
 You can install the [latest release](https://github.com/icicle-emu/icicle-python/releases) from [PyPI](https://pypi.org/project/icicle-emu):
 
 ```
-pip -m install icicle-emu
+pip install icicle-emu
 ```
 
 ## Development
 
-_Note_: You need to install [Rust 1.48](https://rustup.rs) or later to build from source.
+_Note_: You need to install [Rust 1.90](https://rustup.rs) or higher to build from source.
 
-Set up a virtual environment:
+### Install uv
 
 ```shell
-python -m venv venv
-# macOS/Linux
-source venv/bin/activate
-# Windows
-venv\Scripts\activate.bat
+# On Windows
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+# On macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
-Get the dependencies and build:
+### Build the project
 
 ```shell
-pip install -r requirements.txt
-python setup.py develop
+# Clone the repository with submodules
+git clone --recursive https://github.com/icicle-emu/icicle-python
+cd icicle-python
+
+# Install dependencies and build
+uv sync
+uv run maturin develop
+```
+
+### Running tests
+
+The `tests` folder contains tests that double as standalone examples. Prefix a function with `test_` to automatically run it:
+
+```shell
+uv run pytest -v
+```
+
+Alternatively you can `uv run tests/example.py` to run/debug the standalone example.
+
+### Building a wheel
+
+```shell
+uv build
 ```

build.rs

@@ -1,4 +1,4 @@
-// Reference: https://pyo3.rs/v0.18.3/building_and_distribution#macos
+// Reference: https://pyo3.rs/v0.27.1/building-and-distribution.html?highlight=build.rs#macos
 fn main() {
     pyo3_build_config::add_extension_module_link_args();
 }

pyproject.toml

@@ -1,7 +1,41 @@
 [build-system]
-requires = [
-    "setuptools",
-    "wheel",
-    "setuptools-rust",
+requires = ["maturin>=1.7,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "icicle-emu"
+version = "1.0.0"
+description = "Python bindings for the Icicle emulator."
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.8"
+classifiers = [
+    "License :: OSI Approved :: Boost Software License 1.0 (BSL-1.0)",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Development Status :: 5 - Production/Stable",
+    "Operating System :: POSIX",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: Microsoft :: Windows",
 ]
-build-backend = "setuptools.build_meta"
+
+[project.urls]
+Homepage = "https://github.com/icicle-emu/icicle-python"
+"Bug Tracker" = "https://github.com/icicle-emu/icicle-python/issues"
+
+[tool.maturin]
+python-source = "python"
+module-name = "icicle.icicle"
+features = ["pyo3/extension-module"]
+
+[dependency-groups]
+dev = [
+    "maturin>=1.7.8",
+    "pytest>=8.3.3",
+    "capstone>=5.0.6",
+    "keystone-engine>=0.9.2",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["*.py"]

python/icicle/Ghidra/Processors/x86/data/languages/ia.sinc

@@ -1145,78 +1145,78 @@ macro ptr8(r,x) {
 
 macro push22(x) {
   mysave:2 = x;
-  SP = SP -2;
-  tmp:$(SIZE) = segment(SS,SP);
+  tmp:$(SIZE) = segment(SS,SP-2);
   *:2 tmp = mysave;
+  SP = SP-2;
 }
 
 macro push24(x) {
   mysave:4 = x;
-  SP = SP-4;
-  tmp:$(SIZE) = segment(SS,SP);
+  tmp:$(SIZE) = segment(SS,SP-4);
   *:4 tmp = mysave;
+  SP = SP-4;
 }
 
 macro push28(x) {
   mysave:8 = x;
-  SP = SP-8;
-  tmp:$(SIZE) = segment(SS,SP);
+  tmp:$(SIZE) = segment(SS,SP-8);
   *:8 tmp = mysave;
+  SP = SP-8;
 }
 
 macro push42(x) {
   mysave:2 = x;
-  $(STACKPTR) = $(STACKPTR) - 2;
-  *:2 $(STACKPTR) = mysave;
+  *:2 ($(STACKPTR)-2) = mysave;
+  $(STACKPTR) = $(STACKPTR)-2;
 }
 
 macro push44(x) {
   mysave:4 = x;
-  $(STACKPTR) = $(STACKPTR) - 4;
-  *:4 $(STACKPTR) = mysave;
+  *:4 ($(STACKPTR)-4) = mysave;
+  $(STACKPTR) = $(STACKPTR)-4;
 }
 
 macro pushseg44(x) {
   mysave:2 = x;
-  $(STACKPTR) = $(STACKPTR) - 4;
-  *:2 $(STACKPTR) = mysave;
+  *:2 ($(STACKPTR)-4) = mysave;
+  $(STACKPTR) = $(STACKPTR)-4;
 }
 
 macro push48(x) {
   mysave:8 = x;
-  $(STACKPTR) = $(STACKPTR) - 8;
-  *:8 $(STACKPTR) = mysave;
+  *:8 ($(STACKPTR)-8) = mysave;
+  $(STACKPTR) = $(STACKPTR)-8;
 }
 
 @ifdef IA64
 macro push82(x) {
   mysave:2 = x;
-  $(STACKPTR) = $(STACKPTR) - 2;
-  *:2 $(STACKPTR) = mysave;
+  *:2 ($(STACKPTR)-2) = mysave;
+  $(STACKPTR) = $(STACKPTR)-2;
 }
 
 macro push84(x) {
   mysave:4 = x;
-  $(STACKPTR) = $(STACKPTR) - 4;
-  *:4 $(STACKPTR) = mysave;
+  *:4 ($(STACKPTR)-4) = mysave;
+  $(STACKPTR) = $(STACKPTR)-4;
 }
 
 macro push88(x) {
   mysave:8 = x;
-  $(STACKPTR) = $(STACKPTR) - 8;
-  *:8 $(STACKPTR) = mysave;
+  *:8 ($(STACKPTR)-8) = mysave;
+  $(STACKPTR) = $(STACKPTR)-8;
 }
 
 macro pushseg82(x) {
   mysave:2 = x;
-  $(STACKPTR) = $(STACKPTR) - 2;
-  *:2 $(STACKPTR) = mysave;
+  *:2 ($(STACKPTR)-2) = mysave;
+  $(STACKPTR) = $(STACKPTR)-2;
 }
 
 macro pushseg88(x) {
   mysave:2 = x;
-  $(STACKPTR) = $(STACKPTR) - 8;
-  *:2 $(STACKPTR) = mysave;
+  *:2 ($(STACKPTR)-8) = mysave;
+  $(STACKPTR) = $(STACKPTR)-8;
 }
 @endif
 
@@ -2728,7 +2728,8 @@ enterFrames: low5 is low5 { tmp:1 = low5; export tmp; }
 # as a NOP.  We treat it as a NOP as well.
 :FSETPM 	is vexMode=0 & byte=0xdb; byte=0xe4	{ } # 80287 set protected mode
 
-:HLT            is vexMode=0 & byte=0xf4                        { goto inst_start; }
+define pcodeop hlt;
+:HLT            is vexMode=0 & byte=0xf4                        { hlt(); }
 
 :IDIV rm8       is vexMode=0 & byte=0xf6;  rm8 & reg_opcode=7 ...           { rm8ext:2 = sext(rm8);
                                                   local quotient = AX s/ rm8ext;  # DE exception if quotient doesn't fit in AL

python/icicle/__init__.py

@@ -1,16 +1,163 @@
-from .icicle import *
+from typing import List, Dict, Tuple
+from enum import Enum
 
-class MemoryError(Exception):
-    def __init__(self, message, code):
+class MemoryProtection(Enum):
+    NoAccess = ...
+    ReadOnly = ...
+    ReadWrite = ...
+    ExecuteOnly = ...
+    ExecuteRead = ...
+    ExecuteReadWrite = ...
+
+class MemoryExceptionCode(Enum):
+    Unallocated = ...
+    Unmapped = ...
+    UnmappedRegisters = ...
+    Uninitialized = ...
+    ReadViolation = ...
+    WriteViolation = ...
+    ExecViolation = ...
+    ReadWatch = ...
+    WriteWatch = ...
+    Unaligned = ...
+    OutOfMemory = ...
+    SelfModifyingCode = ...
+    AddressOverflow = ...
+    Unknown = ...
+
+class RunStatus(Enum):
+    Running = ...
+    InstructionLimit = ...
+    Breakpoint = ...
+    Interrupted = ...
+    Halt = ...
+    Killed = ...
+    Deadlock = ...
+    OutOfMemory = ...
+    Unimplemented = ...
+    UnhandledException = ...
+
+class ExceptionCode(Enum):
+    NoException = ...
+    InstructionLimit = ...
+    Halt = ...
+    Sleep = ...
+    Syscall = ...
+    CpuStateChanged = ...
+    DivisionException = ...
+    ReadUnmapped = ...
+    ReadPerm = ...
+    ReadUnaligned = ...
+    ReadWatch = ...
+    ReadUninitialized = ...
+    WriteUnmapped = ...
+    WritePerm = ...
+    WriteWatch = ...
+    WriteUnaligned = ...
+    ExecViolation = ...
+    SelfModifyingCode = ...
+    OutOfMemory = ...
+    AddressOverflow = ...
+    InvalidInstruction = ...
+    UnknownInterrupt = ...
+    UnknownCpuID = ...
+    InvalidOpSize = ...
+    InvalidFloatSize = ...
+    CodeNotTranslated = ...
+    ShadowStackOverflow = ...
+    ShadowStackInvalid = ...
+    InvalidTarget = ...
+    UnimplementedOp = ...
+    ExternalAddr = ...
+    Environment = ...
+    JitError = ...
+    InternalError = ...
+    UnmappedRegister = ...
+    UnknownError = ...
+
+class Icicle:
+    def __init__(self, architecture: str, *,
+                 jit = True,
+                 jit_mem = True,
+                 shadow_stack = False,
+                 recompilation = True,
+                 track_uninitialized = False,
+                 optimize_instructions = True,
+                 optimize_block = False,
+                 tracing = False,
+                 ) -> None: ...
+
+    @property
+    def architecture(self) -> str: ...
+
+    @property
+    def exception_code(self) -> ExceptionCode: ...
+
+    @property
+    def exception_value(self) -> int: ...
+
+    icount: int
+
+    icount_limit: int
+
+    pc: int
+
+    sp: int
+
+    """
+    Physical memory capacity in pages (adjust when seeing OutOfMemory)
+    The default limit is set so that the maximum corresponds to ~400 MB of host memory.
+    """
+    mem_capacity: int
+
+    # TODO: API to get memory information?
+
+    def mem_map(self, address: int, size: int, protection: MemoryProtection): ...
+
+    def mem_unmap(self, address: int, size: int): ...
+
+    def mem_protect(self, address: int, size: int, protection: MemoryProtection): ...
+
+    def mem_read(self, address: int, size: int) -> bytes: ...
+
+    def mem_write(self, address: int, data: bytes) -> None: ...
+
+    def reg_list(self) -> Dict[str, Tuple[int, int]]: ...
+
+    def reg_offset(self, name: str) -> int: ...
+
+    def reg_size(self, name: str) -> int: ...
+
+    def reg_read(self, name: str) -> int: ...
+
+    def reg_write(self, name: str, value: int) -> None: ...
+
+    def reset(self): ...
+
+    def run(self) -> RunStatus: ...
+
+    def run_until(self, address: int) -> RunStatus: ...
+
+    def step(self, count: int) -> RunStatus: ...
+
+    def add_breakpoint(self, address: int) -> bool: ...
+
+    def remove_breakpoint(self, address: int) -> bool: ...
+
+def architectures() -> List[str]: ...
+
+class MemoryException(Exception):
+    def __init__(self, message: str, code: MemoryExceptionCode):
         super().__init__(message)
         self.code = code
+
     def __str__(self):
-        return f"{super().__str__()}: {self.code}"
+        return f"{super().__str__()} ({self.code})"
 
 def __ghidra_init():
     import os
     for path in __path__ + [os.getenv("GHIDRA_SRC", ".")]:
-        processors_dir = os.path.join(path, "Ghidra/Processors")
+        processors_dir = os.path.join(path, "Ghidra", "Processors")
         if os.path.isdir(processors_dir):
             os.putenv("GHIDRA_SRC", path)
             os.environ["GHIDRA_SRC"] = path
@@ -18,3 +165,6 @@ def __ghidra_init():
     raise FileNotFoundError("Ghidra processor definitions not found")
 
 __ghidra_init()
+
+# NOTE: This overrides the stubs at runtime with the actual implementation
+from .icicle import *

python/icicle/icicle.pyi

@@ -1,135 +0,0 @@
-from typing import List, Dict, Tuple
-from enum import Enum
-
-class MemoryProtection(Enum):
-    NoAccess = ...
-    ReadOnly = ...
-    ReadWrite = ...
-    ExecuteOnly = ...
-    ExecuteRead = ...
-    ExecuteReadWrite = ...
-
-class MemoryErrorCode(Enum):
-    Unallocated = ...
-    Unmapped = ...
-    Uninitialized = ...
-    ReadViolation = ...
-    WriteViolation = ...
-    ExecViolation = ...
-    ReadWatch = ...
-    WriteWatch = ...
-    Unaligned = ...
-    OutOfMemory = ...
-    SelfModifyingCode = ...
-    AddressOverflow = ...
-    Unknown = ...
-
-class RunStatus(Enum):
-    Running = ...
-    InstructionLimit = ...
-    Breakpoint = ...
-    Interrupted = ...
-    Halt = ...
-    Killed = ...
-    Deadlock = ...
-    OutOfMemory = ...
-    Unimplemented = ...
-    UnhandledException = ...
-
-class ExceptionCode(Enum):
-    NoException = ...
-    InstructionLimit = ...
-    Halt = ...
-    Sleep = ...
-    Syscall = ...
-    CpuStateChanged = ...
-    DivideByZero = ...
-    ReadUnmapped = ...
-    ReadPerm = ...
-    ReadUnaligned = ...
-    ReadWatch = ...
-    ReadUninitialized = ...
-    WriteUnmapped = ...
-    WritePerm = ...
-    WriteWatch = ...
-    WriteUnaligned = ...
-    ExecViolation = ...
-    SelfModifyingCode = ...
-    OutOfMemory = ...
-    AddressOverflow = ...
-    InvalidInstruction = ...
-    UnknownInterrupt = ...
-    UnknownCpuID = ...
-    InvalidOpSize = ...
-    InvalidFloatSize = ...
-    CodeNotTranslated = ...
-    ShadowStackOverflow = ...
-    ShadowStackInvalid = ...
-    InvalidTarget = ...
-    UnimplementedOp = ...
-    ExternalAddr = ...
-    Environment = ...
-    JitError = ...
-    InternalError = ...
-    UnknownError = ...
-
-class MemoryError(Exception):
-    code: MemoryErrorCode
-
-class Icicle:
-    def __init__(self, architecture: str, *,
-                 jit = True,
-                 jit_mem = True,
-                 shadow_stack = True,
-                 recompilation = True,
-                 track_uninitialized = False,
-                 optimize_instructions = True,
-                 optimize_block = True,
-                 tracing = False,
-                 ) -> None: ...
-
-    @property
-    def exception_code(self) -> ExceptionCode: ...
-
-    @property
-    def exception_value(self) -> int: ...
-
-    icount: int
-
-    icount_limit: int
-
-    # TODO: API to get memory information?
-
-    def mem_map(self, address: int, size: int, protection: MemoryProtection): ...
-
-    def mem_unmap(self, address: int, size: int): ...
-
-    def mem_protect(self, address: int, size: int, protection: MemoryProtection): ...
-
-    def mem_read(self, address: int, size: int) -> bytes: ...
-
-    def mem_write(self, address: int, data: bytes) -> None: ...
-
-    def reg_list(self) -> Dict[str, Tuple[int, int]]: ...
-
-    def reg_offset(self, name: str) -> int: ...
-
-    def reg_size(self, name: str) -> int: ...
-
-    def reg_read(self, name: str) -> int: ...
-
-    def reg_write(self, name: str, value: int) -> None: ...
-
-    def reset(self): ...
-
-    def run(self) -> RunStatus: ...
-
-    def run_until(self, address: int) -> RunStatus: ...
-
-    def step(self, count: int) -> RunStatus: ...
-
-    def add_breakpoint(self, address: int) -> bool: ...
-
-    def remove_breakpoint(self, address: int) -> bool: ...
-
-def architectures() -> List[str]: ...

requirements.txt

@@ -1,3 +0,0 @@
-setuptools
-wheel
-setuptools-rust

setup.cfg

@@ -1,34 +0,0 @@
-[metadata]
-name = icicle-emu
-version = 1.0.0
-url = https://github.com/icicle-emu/icicle-python
-project_urls =
-    Bug Tracker = https://github.com/icicle-emu/icicle-python/issues
-description = Python bindings for the Icicle emulator.
-long_description = file: README.md
-long_description_content_type = text/markdown
-classifiers =
-    License :: OSI Approved :: Boost Software License 1.0 (BSL-1.0)
-    Intended Audience :: Developers
-    Programming Language :: Python :: 3
-    Programming Language :: Python :: 3.7
-    Programming Language :: Python :: 3.8
-    Programming Language :: Python :: 3.9
-    Programming Language :: Python :: 3.10
-    Programming Language :: Python :: 3.11
-    Development Status :: 5 - Production/Stable
-    Operating System :: POSIX
-    Operating System :: MacOS :: MacOS X
-    Operating System :: Microsoft :: Windows
-
-[options]
-packages = icicle
-package_dir =
-    = python
-zip_safe = False
-setup_requires = setuptools-rust >= 0.12.1;
-python_requires = >=3.7
-
-# Reference: https://stackoverflow.com/a/64789489/1806760
-[options.package_data]
-icicle = Ghidra/**/*

setup.py

@@ -1,31 +0,0 @@
-#!/usr/bin/env python
-
-import sys
-from os import getenv
-from shutil import which
-from setuptools import find_packages, setup
-from setuptools_rust import RustExtension
-
-if __name__ == "__main__":
-    if "sdist" not in sys.argv and which("cargo") is None:
-        raise FileNotFoundError(f"Rust not found, visit https://rustup.rs for installation instructions")
-
-    ref_name = getenv("GITHUB_REF_NAME")
-    if getenv("GITHUB_REF", "").startswith("refs/tags/") and ref_name:
-        from pkg_resources import parse_version
-        try:
-            parse_version(ref_name)
-            print(f"injecting version = {ref_name} into setup.cfg")
-            with open("setup.cfg", "r") as f:
-                lines = f.readlines()
-            with open("setup.cfg", "w") as f:
-                for line in lines:
-                    if line.startswith("version = "):
-                        line = f"version = {ref_name}\n"
-                    f.write(line)
-        except Exception:
-            pass
-
-    setup(
-        rust_extensions=[RustExtension("icicle.icicle")],
-    )

src/lib.rs

@@ -1,22 +1,36 @@
 use std::borrow::Cow;
 use std::collections::HashMap;
 use icicle_cpu::mem::{Mapping, MemError, perm};
-use icicle_cpu::{ExceptionCode, VmExit};
+use icicle_cpu::{Cpu, ExceptionCode, ValueSource, VmExit};
 use pyo3::prelude::*;
-use icicle_vm;
-use icicle_vm::linux::LinuxCpu;
 use pyo3::exceptions::*;
-use target_lexicon;
 use indexmap::IndexMap;
+use target_lexicon::Architecture;
 use sleigh_runtime::NamedRegister;
 
 // References:
 // - https://pyo3.rs/main/conversions/tables
 // - https://pyo3.rs/main/class
 
-#[pyclass(module = "icicle")]
-#[derive(Clone)]
-enum MemoryProtection {
+struct X86FlagsRegHandler {
+    pub eflags: pcode::VarNode,
+}
+
+impl icicle_cpu::RegHandler for X86FlagsRegHandler {
+    fn read(&mut self, cpu: &mut Cpu) {
+        let eflags = icicle_vm::x86::eflags(cpu);
+        cpu.write_var::<u32>(self.eflags, eflags);
+    }
+
+    fn write(&mut self, cpu: &mut Cpu) {
+        let eflags = cpu.read_var::<u32>(self.eflags);
+        icicle_vm::x86::set_eflags(cpu, eflags);
+    }
+}
+
+#[pyclass(eq, eq_int, module = "icicle")]
+#[derive(Clone, Debug, PartialEq)]
+pub enum MemoryProtection {
     NoAccess,
     ReadOnly,
     ReadWrite,
@@ -25,9 +39,9 @@ enum MemoryProtection {
     ExecuteReadWrite,
 }
 
-#[pyclass(module = "icicle")]
-#[derive(Clone)]
-enum RunStatus {
+#[pyclass(eq, eq_int, module = "icicle")]
+#[derive(Clone, Debug, PartialEq)]
+pub enum RunStatus {
     /// The VM is still running.
     Running,
 
@@ -59,10 +73,12 @@ enum RunStatus {
     UnhandledException,
 }
 
-#[pyclass(module = "icicle")]
-enum MemoryErrorCode {
+#[pyclass(eq, eq_int, module = "icicle")]
+#[derive(Clone, Debug, PartialEq)]
+pub enum MemoryExceptionCode {
     Unallocated,
     Unmapped,
+    UnmappedRegister,
     Uninitialized,
     ReadViolation,
     WriteViolation,
@@ -76,29 +92,30 @@ enum MemoryErrorCode {
     Unknown,
 }
 
-impl From<MemError> for MemoryErrorCode {
+impl From<MemError> for MemoryExceptionCode {
     fn from(value: MemError) -> Self {
         match value {
-            MemError::Unallocated => MemoryErrorCode::Unallocated,
-            MemError::Unmapped => MemoryErrorCode::Unmapped,
-            MemError::Uninitalized => MemoryErrorCode::Uninitialized,
-            MemError::ReadViolation => MemoryErrorCode::ReadViolation,
-            MemError::WriteViolation => MemoryErrorCode::WriteViolation,
-            MemError::ExecViolation => MemoryErrorCode::ExecViolation,
-            MemError::ReadWatch => MemoryErrorCode::ReadWatch,
-            MemError::WriteWatch => MemoryErrorCode::WriteWatch,
-            MemError::Unaligned => MemoryErrorCode::Unaligned,
-            MemError::OutOfMemory => MemoryErrorCode::OutOfMemory,
-            MemError::SelfModifyingCode => MemoryErrorCode::SelfModifyingCode,
-            MemError::AddressOverflow => MemoryErrorCode::AddressOverflow,
-            MemError::Unknown => MemoryErrorCode::Unknown,
+            MemError::Unallocated => MemoryExceptionCode::Unallocated,
+            MemError::Unmapped => MemoryExceptionCode::Unmapped,
+            MemError::UnmappedRegister => MemoryExceptionCode::UnmappedRegister,
+            MemError::Uninitalized => MemoryExceptionCode::Uninitialized,
+            MemError::ReadViolation => MemoryExceptionCode::ReadViolation,
+            MemError::WriteViolation => MemoryExceptionCode::WriteViolation,
+            MemError::ExecViolation => MemoryExceptionCode::ExecViolation,
+            MemError::ReadWatch => MemoryExceptionCode::ReadWatch,
+            MemError::WriteWatch => MemoryExceptionCode::WriteWatch,
+            MemError::Unaligned => MemoryExceptionCode::Unaligned,
+            MemError::OutOfMemory => MemoryExceptionCode::OutOfMemory,
+            MemError::SelfModifyingCode => MemoryExceptionCode::SelfModifyingCode,
+            MemError::AddressOverflow => MemoryExceptionCode::AddressOverflow,
+            MemError::Unknown => MemoryExceptionCode::Unknown,
         }
     }
 }
 
-#[pyclass(module = "icicle", name = "ExceptionCode")]
-#[derive(Clone)]
-enum ExceptionCodePy {
+#[pyclass(eq, eq_int, module = "icicle", name = "ExceptionCode")]
+#[derive(Clone, Debug, PartialEq)]
+pub enum ExceptionCodePy {
     NoException = 0x0000,
 
     InstructionLimit = 0x0001,
@@ -108,7 +125,7 @@ enum ExceptionCodePy {
 
     Syscall = 0x0101,
     CpuStateChanged = 0x0102,
-    DivideByZero = 0x0103,
+    DivisionException = 0x0103,
 
     ReadUnmapped = 0x0201,
     ReadPerm = 0x0202,
@@ -144,6 +161,7 @@ enum ExceptionCodePy {
 
     JitError = 0x3001,
     InternalError = 0x3002,
+    UnmappedRegister = 0x3003,
 
     UnknownError,
 }
@@ -158,7 +176,7 @@ impl From<ExceptionCode> for ExceptionCodePy {
             ExceptionCode::SoftwareBreakpoint => ExceptionCodePy::SoftwareBreakpoint,
             ExceptionCode::Syscall => ExceptionCodePy::Syscall,
             ExceptionCode::CpuStateChanged => ExceptionCodePy::CpuStateChanged,
-            ExceptionCode::DivideByZero => ExceptionCodePy::DivideByZero,
+            ExceptionCode::DivisionException => ExceptionCodePy::DivisionException,
             ExceptionCode::ReadUnmapped => ExceptionCodePy::ReadUnmapped,
             ExceptionCode::ReadPerm => ExceptionCodePy::ReadPerm,
             ExceptionCode::ReadUnaligned => ExceptionCodePy::ReadUnaligned,
@@ -187,17 +205,18 @@ impl From<ExceptionCode> for ExceptionCodePy {
             ExceptionCode::Environment => ExceptionCodePy::Environment,
             ExceptionCode::JitError => ExceptionCodePy::JitError,
             ExceptionCode::InternalError => ExceptionCodePy::InternalError,
+            ExceptionCode::UnmappedRegister => ExceptionCodePy::UnmappedRegister,
             ExceptionCode::UnknownError => ExceptionCodePy::UnknownError,
         }
     }
 }
 
 #[allow(non_snake_case)]
-fn raise_MemoryError(message: String, e: MemError) -> PyErr {
-    Python::with_gil(|py| {
+fn raise_MemoryException(message: String, e: MemError) -> PyErr {
+    Python::attach(|py| {
         let icicle = py.import("icicle").unwrap();
-        let exception = icicle.getattr("MemoryError").unwrap();
-        let args = (message, MemoryErrorCode::from(e));
+        let exception = icicle.getattr("MemoryException").unwrap();
+        let args = (message, MemoryExceptionCode::from(e));
         let inst = exception.call1(args).unwrap();
         PyErr::from_value(inst)
     })
@@ -215,13 +234,14 @@ fn convert_protection(protection: MemoryProtection) -> u8 {
 }
 
 #[pyclass(unsendable, module = "icicle")]
-struct Icicle {
+pub struct Icicle {
+    architecture: String,
     vm: icicle_vm::Vm,
     regs: HashMap<String, NamedRegister>,
 }
 
 fn reg_find<'a>(i: &'a Icicle, name: &str) -> PyResult<&'a NamedRegister> {
-    let sleigh = i.vm.cpu.sleigh();
+    let sleigh = &i.vm.cpu.arch.sleigh;
     match sleigh.get_reg(name) {
         None => {
             i.regs.get(name.to_lowercase().as_str())
@@ -233,51 +253,99 @@ fn reg_find<'a>(i: &'a Icicle, name: &str) -> PyResult<&'a NamedRegister> {
     }
 }
 
+fn reg_var<'a>(i: &'a Icicle, name: &str) -> PyResult<pcode::VarNode> {
+    let var = reg_find(i, name)?.get_var();
+    var.ok_or(PyKeyError::new_err(format!("Register var too large: {name}")))
+}
+
 #[pymethods]
 impl Icicle {
     #[getter]
-    fn get_icount_limit(&mut self) -> u64 {
+    pub fn get_icount_limit(&mut self) -> u64 {
         self.vm.icount_limit
     }
 
     #[setter]
-    fn set_icount_limit(&mut self, value: u64) {
+    pub fn set_icount_limit(&mut self, value: u64) {
         self.vm.icount_limit = value;
     }
 
     #[getter]
-    fn get_icount(&mut self) -> u64 {
-        return self.vm.cpu.icount;
+    pub fn get_icount(&mut self) -> u64 {
+        self.vm.cpu.icount
     }
 
     #[setter]
-    fn set_icount(&mut self, value: u64) {
+    pub fn set_icount(&mut self, value: u64) {
         self.vm.cpu.icount = value;
     }
 
     #[getter]
-    fn get_exception_code(&self) -> ExceptionCodePy {
+    pub fn get_exception_code(&self) -> ExceptionCodePy {
         ExceptionCode::from_u32(self.vm.cpu.exception.code).into()
     }
 
     #[getter]
-    fn get_exception_value(&self) -> u64 {
+    pub fn get_exception_value(&self) -> u64 {
         self.vm.cpu.exception.value
     }
 
+    #[getter]
+    pub fn get_architecture(&self) -> String {
+        self.architecture.to_string()
+    }
+
+    #[getter]
+    pub fn get_pc(&self) -> u64 {
+        self.vm.cpu.read_pc()
+    }
+
+    #[setter]
+    pub fn set_pc(&mut self, address: u64) {
+        self.vm.cpu.write_pc(address)
+    }
+
+    #[getter]
+    pub fn get_sp(&mut self) -> u64 {
+        self.vm.cpu.read_reg(self.vm.cpu.arch.reg_sp)
+    }
+
+    #[setter]
+    pub fn set_sp(&mut self, address: u64) {
+        self.vm.cpu.write_reg(self.vm.cpu.arch.reg_sp, address)
+    }
+
+    #[getter]
+    pub fn get_mem_capacity(&self) -> usize {
+        self.vm.cpu.mem.capacity()
+    }
+
+    #[setter]
+    pub fn set_mem_capacity(&mut self, capacity: usize) -> PyResult<()> {
+        if self.vm.cpu.mem.set_capacity(capacity) {
+            return Ok(());
+        }
+        Err(
+            raise_MemoryException(
+                format!("Reducing memory capacity is not supported"),
+                MemError::Unknown,
+            )
+        )
+    }
+
     #[new]
     #[pyo3(signature = (
         architecture,
         jit = true,
         jit_mem = true,
-        shadow_stack = true,
+        shadow_stack = false,
         recompilation = true,
         track_uninitialized = false,
         optimize_instructions = true,
-        optimize_block = true,
+        optimize_block = false,
         tracing = false,
     ))]
-    fn new(
+    pub fn new(
         architecture: String,
         jit: bool,
         jit_mem: bool,
@@ -304,11 +372,11 @@ impl Icicle {
             }
         }
 
-        // Setup the CPU state for the target triple
+        // Set up the CPU state for the target triple
         let mut config = icicle_vm::cpu::Config::from_target_triple(
             format!("{architecture}-none").as_str()
         );
-        if config.triple.architecture == target_lexicon::Architecture::Unknown {
+        if config.triple.architecture == Architecture::Unknown {
             return Err(
                 PyException::new_err(format!("Unknown architecture: {architecture}"))
             );
@@ -323,45 +391,57 @@ impl Icicle {
         config.optimize_instructions = optimize_instructions;
         config.optimize_block = optimize_block;
 
-        let vm = icicle_vm::build(&config)
+        let mut vm = icicle_vm::build(&config)
             .map_err(|e| {
                 PyException::new_err(format!("VM build error: {e}"))
             })?;
 
         // Populate the lowercase register map
         let mut regs = HashMap::new();
-        let sleigh = vm.cpu.sleigh();
+        let sleigh = &vm.cpu.arch.sleigh;
         for reg in &sleigh.named_registers {
             let name = sleigh.get_str(reg.name);
             regs.insert(name.to_lowercase(), reg.clone());
         }
 
+        // Special handling for x86 flags
+        match config.triple.architecture {
+            Architecture::X86_32(_) | Architecture::X86_64 | Architecture::X86_64h => {
+                let eflags = sleigh.get_reg("eflags").unwrap().get_var().unwrap();
+                let reg_handler = X86FlagsRegHandler { eflags };
+                vm.cpu.add_reg_handler(eflags.id, Box::new(reg_handler));
+            }
+            _ => {}
+        }
+
         Ok(Icicle {
+            architecture,
             vm,
             regs,
         })
     }
 
-    fn __str__(&mut self) -> String {
+    pub fn __str__(&mut self) -> String {
         let arch = &self.vm.cpu.arch;
         let endianness = if arch.sleigh.big_endian {
             "big endian"
         } else {
             "little endian"
         };
-        format!("Icicle VM for {0:?} ({endianness})", arch.triple.architecture)
+        format!("Icicle VM for {0:?} ({endianness})", self.architecture)
     }
 
-    fn mem_map(&mut self, address: u64, size: u64, protection: MemoryProtection) -> PyResult<()> {
+    pub fn mem_map(&mut self, address: u64, size: u64, protection: MemoryProtection) -> PyResult<()> {
+        let init_perm = if self.vm.cpu.mem.track_uninitialized { perm::NONE } else { perm::INIT };
         let mapping = Mapping {
-            perm: convert_protection(protection),
+            perm: convert_protection(protection) | init_perm,
             value: 0,
         };
         if self.vm.cpu.mem.map_memory_len(address, size, mapping) {
             Ok(())
         } else {
             Err(
-                raise_MemoryError(
+                raise_MemoryException(
                     format!("Failed to map memory {address:X}[{size:X}]"),
                     MemError::Unknown,
                 )
@@ -369,12 +449,12 @@ impl Icicle {
         }
     }
 
-    fn mem_unmap(&mut self, address: u64, size: u64) -> PyResult<()> {
+    pub fn mem_unmap(&mut self, address: u64, size: u64) -> PyResult<()> {
         if self.vm.cpu.mem.unmap_memory_len(address, size) {
             Ok(())
         } else {
             Err(
-                raise_MemoryError(
+                raise_MemoryException(
                     format!("Failed to unmap memory {address:X}[{size:X}]"),
                     MemError::Unknown,
                 )
@@ -382,10 +462,10 @@ impl Icicle {
         }
     }
 
-    fn mem_protect(&mut self, address: u64, size: usize, protection: MemoryProtection) -> PyResult<()> {
+    pub fn mem_protect(&mut self, address: u64, size: usize, protection: MemoryProtection) -> PyResult<()> {
         self.vm.cpu.mem.update_perm(address, size as u64, convert_protection(protection))
             .map_err(|e| {
-                raise_MemoryError(
+                raise_MemoryException(
                     format!("Failed to protect memory {address:X}[{size:X}]"),
                     e,
                 )
@@ -393,7 +473,7 @@ impl Icicle {
         Ok(())
     }
 
-    fn mem_read(&mut self, address: u64, size: usize) -> PyResult<Cow<[u8]>> {
+    pub fn mem_read(&mut self, address: u64, size: usize) -> PyResult<Cow<'_, [u8]>> {
         // Allocate a buffer
         let mut buffer = Vec::with_capacity(size);
         buffer.resize(size, 0);
@@ -401,56 +481,65 @@ impl Icicle {
         // Read the memory
         self.vm.cpu.mem.read_bytes(address, &mut buffer[..], perm::NONE)
             .map_err(|e| {
-                raise_MemoryError(
+                raise_MemoryException(
                     format!("Failed to read memory {address:X}[{size:X}]"),
                     e,
                 )
             })?;
-        return Ok(Cow::Owned(buffer));
+        Ok(Cow::Owned(buffer))
     }
 
-    fn mem_write(&mut self, address: u64, data: Vec<u8>) -> PyResult<()> {
+    pub fn mem_write(&mut self, address: u64, data: Vec<u8>) -> PyResult<()> {
         let size = data.len();
         self.vm.cpu.mem.write_bytes(address, &data[..], perm::NONE)
             .map_err(|e| {
-                raise_MemoryError(
+                raise_MemoryException(
                     format!("Failed to write memory {address:X}[{size:X}]"),
                     e,
                 )
             })
     }
 
-    fn reg_list(&self) -> PyResult<IndexMap<String, (u32, u8)>> {
+    pub fn reg_list(&self) -> PyResult<IndexMap<String, (u32, u8)>> {
         let mut result = IndexMap::new();
-        let sleigh = self.vm.cpu.sleigh();
+        let sleigh = &self.vm.cpu.arch.sleigh;
         for reg in &sleigh.named_registers {
             let name = sleigh.get_str(reg.name);
-            result.insert(name.to_string(), (reg.offset, reg.var.size));
+            let var = reg.get_var();
+            if let Some(var) = var {
+                result.insert(name.to_string(), (reg.offset, var.size));
+            }
         }
-        return Ok(result);
+        Ok(result)
     }
 
-    fn reg_offset(&self, name: &str) -> PyResult<u32> {
+    pub fn reg_offset(&self, name: &str) -> PyResult<u32> {
         Ok(reg_find(self, name)?.offset)
     }
 
-    fn reg_size(&self, name: &str) -> PyResult<u8> {
-        Ok(reg_find(self, name)?.var.size)
+    pub fn reg_size(&self, name: &str) -> PyResult<u8> {
+        Ok(reg_var(self, name)?.size)
     }
 
-    fn reg_read(&mut self, name: &str) -> PyResult<u64> {
-        Ok(self.vm.cpu.read_reg(reg_find(self, name)?.var))
+    pub fn reg_read(&mut self, name: &str) -> PyResult<u64> {
+        Ok(self.vm.cpu.read_reg(reg_var(self, name)?))
     }
 
-    fn reg_write(&mut self, name: &str, value: u64) -> PyResult<()> {
-        Ok(self.vm.cpu.write_reg(reg_find(self, name)?.var, value))
+    pub fn reg_write(&mut self, name: &str, value: u64) -> PyResult<()> {
+        let var = reg_var(self, name)?;
+        if var == self.vm.cpu.arch.reg_pc {
+            self.vm.cpu.write_pc(value);
+        } else {
+            self.vm.cpu.write_reg(var, value);
+        }
+        Ok(())
     }
 
-    fn reset(&mut self) {
+    pub fn reset(&mut self) {
         self.vm.reset();
     }
 
-    fn run(&mut self) -> RunStatus {
+    pub fn run(&mut self) -> RunStatus {
         match self.vm.run() {
             VmExit::Running => RunStatus::Running,
             VmExit::InstructionLimit => RunStatus::InstructionLimit,
@@ -465,7 +554,7 @@ impl Icicle {
         }
     }
 
-    fn run_until(&mut self, address: u64) -> RunStatus {
+    pub fn run_until(&mut self, address: u64) -> RunStatus {
         let breakpoint_added = self.vm.add_breakpoint(address);
         let status = self.run();
         if breakpoint_added {
@@ -474,7 +563,7 @@ impl Icicle {
         status
     }
 
-    fn step(&mut self, count: u64) -> RunStatus {
+    pub fn step(&mut self, count: u64) -> RunStatus {
         let old_limit = self.vm.icount_limit;
         self.vm.icount_limit = self.vm.cpu.icount.saturating_add(count);
         let status = self.run();
@@ -482,17 +571,17 @@ impl Icicle {
         status
     }
 
-    fn add_breakpoint(&mut self, address: u64) -> bool {
+    pub fn add_breakpoint(&mut self, address: u64) -> bool {
         self.vm.add_breakpoint(address)
     }
 
-    fn remove_breakpoint(&mut self, address: u64) -> bool {
+    pub fn remove_breakpoint(&mut self, address: u64) -> bool {
         self.vm.remove_breakpoint(address)
     }
 }
 
 #[pyfunction]
-fn architectures() -> PyResult<Vec<&'static str>> {
+pub fn architectures() -> PyResult<Vec<&'static str>> {
     Ok(vec![
         "i686",
         "x86_64",
@@ -504,11 +593,11 @@ fn architectures() -> PyResult<Vec<&'static str>> {
 /// the `lib.name` setting in the `Cargo.toml`, else Python will not be able to
 /// import the module.
 #[pymodule]
-fn icicle(_: Python<'_>, m: &PyModule) -> PyResult<()> {
+fn icicle(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(architectures, m)?)?;
     m.add_class::<Icicle>()?;
     m.add_class::<MemoryProtection>()?;
-    m.add_class::<MemoryErrorCode>()?;
+    m.add_class::<MemoryExceptionCode>()?;
     m.add_class::<RunStatus>()?;
     m.add_class::<ExceptionCodePy>()?;
     Ok(())

src/main.rs

@@ -1,379 +0,0 @@
-use std::borrow::Cow;
-use std::collections::HashMap;
-use icicle_cpu::mem::{Mapping, perm};
-use icicle_cpu::{VmExit};
-use icicle_vm;
-use icicle_vm::linux::LinuxCpu;
-use target_lexicon;
-use indexmap::IndexMap;
-use sleigh_runtime::NamedRegister;
-
-#[allow(dead_code)]
-#[derive(Clone)]
-enum MemoryProtection {
-    NoAccess,
-    ReadOnly,
-    ReadWrite,
-    ExecuteOnly,
-    ExecuteRead,
-    ExecuteReadWrite,
-}
-
-struct Icicle {
-    vm: icicle_vm::Vm,
-    regs: HashMap<String, NamedRegister>,
-}
-
-fn convert_protection(protection: MemoryProtection) -> u8 {
-    match protection {
-        MemoryProtection::NoAccess => perm::NONE,
-        MemoryProtection::ReadOnly => perm::READ,
-        MemoryProtection::ReadWrite => perm::READ | perm::WRITE,
-        MemoryProtection::ExecuteOnly => perm::EXEC,
-        MemoryProtection::ExecuteRead => perm::EXEC | perm::READ,
-        MemoryProtection::ExecuteReadWrite => perm::EXEC | perm::READ | perm::WRITE,
-    }
-}
-
-fn reg_find<'a>(i: &'a Icicle, name: &str) -> Result<&'a NamedRegister, String> {
-    let sleigh = i.vm.cpu.sleigh();
-    match sleigh.get_reg(name) {
-        None => {
-            i.regs.get(name.to_lowercase().as_str())
-                .ok_or(
-                    format!("Register not found: {name}")
-                )
-        }
-        Some(r) => Ok(r),
-    }
-}
-
-impl Icicle {
-    #[allow(dead_code)]
-    fn get_icount_limit(&mut self) -> u64 {
-        self.vm.icount_limit
-    }
-
-    #[allow(dead_code)]
-    fn set_icount_limit(&mut self, value: u64) {
-        self.vm.icount_limit = value;
-    }
-
-    #[allow(dead_code)]
-    fn get_icount(&mut self) -> u64 {
-        return self.vm.cpu.icount;
-    }
-
-    #[allow(dead_code)]
-    fn set_icount(&mut self, value: u64) {
-        self.vm.cpu.icount = value;
-    }
-
-    fn new(
-        architecture: String,
-        jit: bool,
-        jit_mem: bool,
-        shadow_stack: bool,
-        recompilation: bool,
-        track_uninitialized: bool,
-        optimize_instructions: bool,
-        optimize_block: bool,
-        tracing: bool,
-    ) -> Result<Self, String> {
-        // Prevent mixing '_' and '-'
-        if architecture.split("-").count() != 1 {
-            return Err(
-                format!("Bad architecture format: {architecture}")
-            );
-        }
-
-        // TODO: support instantiating this multiple times
-        if tracing {
-            tracing_subscriber::fmt()
-                .with_max_level(tracing::Level::DEBUG)
-                .with_target(false)
-                .init();
-        }
-
-        // Setup the CPU state for the target triple
-        let mut config = icicle_vm::cpu::Config::from_target_triple(
-            format!("{architecture}-none").as_str()
-        );
-        if config.triple.architecture == target_lexicon::Architecture::Unknown {
-            return Err(
-                format!("Unknown architecture: {architecture}")
-            );
-        }
-
-        // Configuration
-        config.enable_jit = jit;
-        config.enable_jit_mem = jit_mem;
-        config.enable_shadow_stack = shadow_stack;
-        config.enable_recompilation = recompilation;
-        config.track_uninitialized = track_uninitialized;
-        config.optimize_instructions = optimize_instructions;
-        config.optimize_block = optimize_block;
-
-        let vm = icicle_vm::build(&config)
-            .map_err(|e| {
-                format!("VM build error: {e}")
-            })?;
-
-        // Populate the lowercase register map
-        let mut regs = HashMap::new();
-        let sleigh = vm.cpu.sleigh();
-        for reg in &sleigh.named_registers {
-            let name = sleigh.get_str(reg.name);
-            regs.insert(name.to_lowercase(), reg.clone());
-        }
-
-        Ok(Icicle {
-            vm,
-            regs,
-        })
-    }
-
-    fn __str__(&mut self) -> String {
-        let arch = &self.vm.cpu.arch;
-        let endianness = if arch.sleigh.big_endian {
-            "big endian"
-        } else {
-            "little endian"
-        };
-        format!("Icicle VM for {0:?} ({endianness})", arch.triple.architecture)
-    }
-
-    fn mem_map(&mut self, address: u64, size: u64, protection: MemoryProtection) -> Result<(), String> {
-        let mapping = Mapping {
-            perm: convert_protection(protection),
-            value: 0,
-        };
-        if self.vm.cpu.mem.map_memory_len(address, size, mapping) {
-            Ok(())
-        } else {
-            Err(
-                format!("Failed to map memory {address:X}[{size:X}]")
-            )
-        }
-    }
-
-    #[allow(dead_code)]
-    fn mem_unmap(&mut self, address: u64, size: u64) -> Result<(), String> {
-        if self.vm.cpu.mem.unmap_memory_len(address, size) {
-            Ok(())
-        } else {
-            Err(
-                format!("Failed to unmap memory {address:X}[{size:X}]")
-            )
-        }
-    }
-
-    fn mem_protect(&mut self, address: u64, size: usize, protection: MemoryProtection) -> Result<(), String> {
-        self.vm.cpu.mem.update_perm(address, size as u64, convert_protection(protection))
-            .map_err(|_| {
-                format!("Failed to protect memory {address:X}[{size:X}]")
-            })?;
-        Ok(())
-    }
-
-    #[allow(dead_code)]
-    fn mem_read(&mut self, address: u64, size: usize) -> Result<Cow<[u8]>, String> {
-        // Allocate a buffer
-        let mut buffer = Vec::with_capacity(size);
-        buffer.resize(size, 0);
-
-        // Read the memory
-        match self.vm.cpu.mem.read_bytes(address, &mut buffer[..], perm::NONE) {
-            Ok(_) => Ok(Cow::Owned(buffer)),
-            Err(_) => Err(format!("Failed to read memory {address:X}[{size:X}]"))
-        }
-    }
-
-    fn mem_write(&mut self, address: u64, data: Vec<u8>) -> Result<(), String> {
-        let size = data.len();
-        match self.vm.cpu.mem.write_bytes(address, &data[..], perm::NONE) {
-            Ok(_) => Ok(()),
-            Err(_) => Err(format!("Failed to write memory {address:X}[{size:X}]"))
-        }
-    }
-
-    #[allow(dead_code)]
-    fn reg_list(&self) -> IndexMap<String, (u32, u8)> {
-        let mut result = IndexMap::new();
-        let sleigh = self.vm.cpu.sleigh();
-        for reg in &sleigh.named_registers {
-            let name = sleigh.get_str(reg.name);
-            result.insert(name.to_string(), (reg.offset, reg.var.size));
-        }
-        return result;
-    }
-
-    #[allow(dead_code)]
-    fn reg_offset(&self, name: &str) -> Result<u32, String> {
-        Ok(reg_find(self, name)?.offset)
-    }
-
-    #[allow(dead_code)]
-    fn reg_size(&self, name: &str) -> Result<u8, String> {
-        Ok(reg_find(self, name)?.var.size)
-    }
-
-    fn reg_read(&mut self, name: &str) -> Result<u64, String> {
-        Ok(self.vm.cpu.read_reg(reg_find(self, name)?.var))
-    }
-
-    fn reg_write(&mut self, name: &str, value: u64) -> Result<(), String> {
-        Ok(self.vm.cpu.write_reg(reg_find(self, name)?.var, value))
-    }
-
-    #[allow(dead_code)]
-    fn reset(&mut self) {
-        self.vm.reset();
-    }
-
-    fn run(&mut self) -> VmExit {
-        self.vm.run()
-    }
-
-    #[allow(dead_code)]
-    fn run_until(&mut self, address: u64) -> VmExit {
-        let breakpoint_added = self.vm.add_breakpoint(address);
-        let status = self.run();
-        if breakpoint_added {
-            self.vm.remove_breakpoint(address);
-        }
-        status
-    }
-
-    #[allow(dead_code)]
-    fn step(&mut self, count: u64) -> VmExit {
-        let old_limit = self.vm.icount_limit;
-        self.vm.icount_limit = self.vm.cpu.icount.saturating_add(count);
-        let status = self.run();
-        self.vm.icount_limit = old_limit;
-        status
-    }
-
-    #[allow(dead_code)]
-    fn add_breakpoint(&mut self, address: u64) -> bool {
-        self.vm.add_breakpoint(address)
-    }
-
-    #[allow(dead_code)]
-    fn remove_breakpoint(&mut self, address: u64) -> bool {
-        self.vm.remove_breakpoint(address)
-    }
-}
-
-#[allow(dead_code)]
-fn architectures() -> Result<Vec<&'static str>, String> {
-    Ok(vec![
-        "i686",
-        "x86_64",
-        "aarch64",
-    ])
-}
-
-fn nx_start() {
-    let mut vm = Icicle::new(
-        "x86_64".to_string(),
-        false,
-        true,
-        true,
-        true,
-        false,
-        true,
-        true,
-        false,
-    ).unwrap();
-    let page = 0x10000;
-    vm.mem_map(page, 0x1000, MemoryProtection::ReadOnly).unwrap();
-    // <non-executable memory> inc eax; ret
-    vm.mem_write(page, b"\xFF\xC0\xC3".to_vec()).unwrap();
-    vm.reg_write("rip", page).unwrap();
-    let status = vm.run();
-    println!("status: {:?}", status);
-    println!("rip: {:#x}", vm.reg_read("rip").unwrap());
-}
-
-fn nx_middle() {
-    let mut vm = Icicle::new(
-        "x86_64".to_string(),
-        false,
-        true,
-        true,
-        true,
-        false,
-        true,
-        true,
-        false,
-    ).unwrap();
-    let page = 0x10000;
-    vm.mem_map(page, 0x2000, MemoryProtection::ExecuteRead).unwrap();
-    vm.mem_protect(page + 0x1000, 0x1000, MemoryProtection::ReadOnly).unwrap();
-    // inc eax; inc eax; <transition to non-executable region>; ret
-    let rip = page + 0x1000 - 2;
-    vm.mem_write(rip, b"\xFF\xC0\xFF\xC0\xC3".to_vec()).unwrap();
-    vm.reg_write("rip", rip).unwrap();
-    let status = vm.run();
-    println!("status: {:?}", status);
-    println!("rip: {:#x}", vm.reg_read("rip").unwrap());
-    println!("rax: {:#x}", vm.reg_read("rax").unwrap());
-}
-
-fn inv_start() {
-    let mut vm = Icicle::new(
-        "x86_64".to_string(),
-        false,
-        true,
-        true,
-        true,
-        false,
-        true,
-        true,
-        false,
-    ).unwrap();
-    let page = 0x10000;
-    vm.mem_map(page, 0x1000, MemoryProtection::ExecuteRead).unwrap();
-    // <invalid>; ret
-    vm.mem_write(page, b"\xFF\xFF\xC3".to_vec()).unwrap();
-    vm.reg_write("rip", page).unwrap();
-    let status = vm.run();
-    println!("status: {:?}", status);
-    println!("rip: {:#x}", vm.reg_read("rip").unwrap());
-    println!("rax: {:#x}", vm.reg_read("rax").unwrap());
-}
-
-fn inv_middle() {
-    let mut vm = Icicle::new(
-        "x86_64".to_string(),
-        false,
-        true,
-        true,
-        true,
-        false,
-        true,
-        true,
-        false,
-    ).unwrap();
-    let page = 0x10000;
-    vm.mem_map(page, 0x1000, MemoryProtection::ExecuteRead).unwrap();
-    // inc eax; <invalid>; ret
-    vm.mem_write(page, b"\xFF\xC0\xFF\xFF\xC3".to_vec()).unwrap();
-    vm.reg_write("rip", page).unwrap();
-    let status = vm.run();
-    println!("status: {:?}", status);
-    println!("rip: {:#x}", vm.reg_read("rip").unwrap());
-    println!("rax: {:#x}", vm.reg_read("rax").unwrap());
-}
-
-fn main() {
-    println!("=== NX (block start) ===");
-    nx_start();
-    println!("=== NX (block middle) ===");
-    nx_middle();
-    println!("=== Invalid instruction (block start) ===");
-    inv_start();
-    println!("=== Invalid instruction (block middle) ===");
-    inv_middle();
-}

tests.rs

@@ -0,0 +1,404 @@
+#![allow(unused)]
+
+use icicle::*;
+use pyo3::PyResult;
+use std::process::exit;
+
+// NOTE: https://github.com/rust-lang/rust-analyzer/issues/18752
+#[test]
+fn example() -> PyResult<()> {
+    Err(pyo3::exceptions::PyException::new_err("test"))
+}
+
+fn new_i686() -> PyResult<()> {
+    let mut vm = Icicle::new("i686".to_string(), true, true, false, true, false, true, false, false)?;
+    assert_eq!(vm.get_architecture(), "i686");
+    Ok(())
+}
+
+fn new_vm(jit: bool) -> PyResult<Icicle> {
+    Icicle::new(
+        "x86_64".to_string(),
+        jit,
+        true,
+        false,
+        true,
+        false,
+        true,
+        false,
+        false,
+    )
+}
+
+fn new_trace_vm(jit: bool) -> PyResult<Icicle> {
+    Icicle::new(
+        "x86_64".to_string(),
+        jit,
+        true,
+        false,
+        true,
+        false,
+        true,
+        false,
+        true,
+    )
+}
+
+fn nx_start() -> PyResult<()> {
+    let mut vm = new_vm(false)?;
+    let page = 0x10000;
+    vm.mem_map(page, 0x1000, MemoryProtection::ReadOnly)?;
+    // <non-executable memory> inc eax; ret
+    vm.mem_write(page, b"\xFF\xC0\xC3".to_vec())?;
+    vm.reg_write("rip", page)?;
+    let status = vm.run();
+    println!("status: {:?}", status);
+    println!("rip: {:#x}", vm.reg_read("rip")?);
+
+    Ok(())
+}
+
+fn nx_middle() -> PyResult<()> {
+    let mut vm = new_vm(false)?;
+    let page = 0x10000;
+    vm.mem_map(page, 0x2000, MemoryProtection::ExecuteRead)?;
+    vm.mem_protect(page + 0x1000, 0x1000, MemoryProtection::ReadOnly)?;
+    // inc eax; inc eax; <transition to non-executable region>; ret
+    let rip = page + 0x1000 - 2;
+    vm.mem_write(rip, b"\xFF\xC0\xFF\xC0\xC3".to_vec())?;
+    vm.reg_write("rip", rip)?;
+    let status = vm.run();
+    println!("status: {:?}", status);
+    println!("rip: {:#x}", vm.reg_read("rip")?);
+    println!("rax: {:#x}", vm.reg_read("rax")?);
+
+    Ok(())
+}
+
+fn inv_start() -> PyResult<()> {
+    let mut vm = new_vm(false)?;
+    let page = 0x10000;
+    vm.mem_map(page, 0x1000, MemoryProtection::ExecuteRead)?;
+    // <invalid>; ret
+    vm.mem_write(page, b"\xFF\xFF\xC3".to_vec())?;
+    vm.reg_write("rip", page)?;
+    let status = vm.run();
+    println!("status: {:?}", status);
+    println!("rip: {:#x}", vm.reg_read("rip")?);
+    println!("rax: {:#x}", vm.reg_read("rax")?);
+
+    Ok(())
+}
+
+fn inv_middle() -> PyResult<()> {
+    let mut vm = new_vm(false)?;
+    let page = 0x10000;
+    vm.mem_map(page, 0x1000, MemoryProtection::ExecuteRead)?;
+    // inc eax; <invalid>; ret
+    vm.mem_write(page, b"\xFF\xC0\xFF\xFF\xC3".to_vec())?;
+    vm.reg_write("rip", page)?;
+    let status = vm.run();
+    println!("status: {:?}", status);
+    println!("rip: {:#x}", vm.reg_read("rip")?);
+    println!("rax: {:#x}", vm.reg_read("rax")?);
+
+    Ok(())
+}
+
+fn block_optimization() -> PyResult<()> {
+    let mut vm: Icicle = Icicle::new(
+        "x86_64".to_string(),
+        true,
+        true,
+        true,
+        true,
+        false,
+        true,
+        true,
+        false,
+    )?;
+
+    // Memory setup
+    let addr: u64 = 0x140001A73;
+    let heap: u64 = 0x71000;
+    vm.mem_map(heap, 0x1000, MemoryProtection::ReadWrite)?;
+    vm.mem_write(heap + 4, b"\x37\x13\x00\x00".to_vec())?;
+    vm.mem_map(addr & !0xFFF, 0x1000, MemoryProtection::ExecuteRead)?;
+    vm.mem_write(addr, b"\x41\xc1\xea\x07\x41\x83\xe2\x1f\x74\x08\x44\x89\xd0\x48\x89\x54\xc6\x08\x49\x83\xc1\x04\x4c\x89\x0e\x4c\x89\xc9\x44\x8b\x11\x44\x89\xd0\xf7\xd0\x49\x89\xc9\xa8\x03\x0f\x84\x88\xf6\xff\xff\xeb\x4c\xcc".to_vec())?;
+
+    // Register setup
+    vm.reg_write("r9", heap)?;
+    vm.reg_write("r10", 0x13)?;
+    vm.reg_write("rip", addr)?;
+    vm.reg_write("rsi", heap + 0x100)?;
+
+    // Step through instructions
+    for i in 0..11 {
+        let rip = vm.reg_read("rip")?;
+        let rcx = vm.reg_read("rcx")?;
+        let r9 = vm.reg_read("r9")?;
+
+        println!("[{}] RIP: {:#x}, RCX: {:#x}, R9: {:#x}", i, rip, rcx, r9);
+
+        if rip == 0x140001A8F {
+            vm.reg_write("r9", 0x13370900)?;
+        }
+
+        vm.step(1);
+
+        if rip == 0x140001A9A {
+            if rcx != r9 {
+                println!("[BUG] expected rcx({:#x}) == r9({:#x})", rcx, r9);
+            } else {
+                println!("Everything works!");
+            }
+        }
+    }
+
+    Ok(())
+}
+
+fn rewind() -> PyResult<()> {
+    let mut vm = new_vm(true)?;
+
+    vm.mem_map(0x100, 0x20, MemoryProtection::ExecuteRead)?;
+    vm.mem_map(0x200, 0x20, MemoryProtection::ReadOnly)?;
+
+    vm.mem_write(0x100, b"\x55\xCC".to_vec())?; // push rbp
+    vm.reg_write("rbp", 0xF00)?;
+    vm.reg_write("rsp", 0x210)?;
+    vm.reg_write("rip", 0x100)?;
+    let status = vm.step(1);
+    println!("run status      : {:?}", status);
+    println!("exception code  : {:?}", vm.get_exception_code());
+    println!("exception value : {:#x}", vm.get_exception_value());
+    println!("stack pointer   : {:#x}", vm.reg_read("rsp")?);
+
+    Ok(())
+}
+
+fn execute_uninitialized() -> PyResult<()> {
+    let mut vm = Icicle::new(
+        "x86_64".to_string(),
+        true,
+        true,
+        false,
+        true,
+        true, // NOTE: setting this to true is not properly supported
+        true,
+        false,
+        false,
+    )?;
+
+    // \x48\x8d\x05\x01\x00\x00\x00\x90\x8a\x18\x90
+
+    vm.mem_map(0x100, 0x20, MemoryProtection::ExecuteOnly)?;
+    vm.mem_write(0x100, b"\x90\xFF\xC0".to_vec())?; // inc eax
+    vm.reg_write("rip", 0x100)?;
+    {
+        println!("[pre1] icount: {}", vm.get_icount());
+        let status = vm.step(2);
+        // NOTE: the real reason is that INIT is not set
+        println!("run status      : {:?}", status);
+        println!("exception code  : {:?}", vm.get_exception_code());
+        println!("exception value : {:#x}", vm.get_exception_value());
+        println!("rax             : {:#x}", vm.reg_read("rax")?);
+    }
+
+    {
+        println!("[pre2] icount: {}", vm.get_icount());
+        let status = vm.step(1);
+        // NOTE: the real reason is that INIT is not set
+        println!("run status      : {:?}", status);
+        println!("exception code  : {:?}", vm.get_exception_code());
+        println!("exception value : {:#x}", vm.get_exception_value());
+        println!("rax             : {:#x}", vm.reg_read("rax")?);
+        println!("[post] icount: {}", vm.get_icount());
+    }
+
+    // TODO: status is now UnhandledException, should be InstructionLimit
+    // on the next stpe it should be UnhandledException -> ExecViolation
+
+    Ok(())
+}
+
+fn execute_only() -> PyResult<()> {
+    let mut vm = new_vm(false)?;
+
+    vm.mem_map(0x100, 0x20, MemoryProtection::ExecuteOnly)?;
+    /*
+    0x100: lea rax, [rip]
+    0x107: nop
+    0x108: mov bl, byte ptr [rax]
+    0x10A: int3
+    */
+    vm.mem_write(
+        0x100,
+        b"\x48\x8d\x05\x00\x00\x00\x00\x90\x8a\x18\xCC".to_vec(),
+    )?; // nop
+    vm.reg_write("rip", 0x100)?;
+    vm.step(2);
+    let status = vm.step(1);
+    // NOTE: the real reason is that INIT is not set
+    println!("run status      : {:?}", status);
+    println!("exception code  : {:?}", vm.get_exception_code());
+    println!("exception value : {:#x}", vm.get_exception_value());
+    println!("bl: {:#x}", vm.reg_read("bl")?);
+    println!("rip: {:#x}", vm.reg_read("rip")?);
+
+    Ok(())
+}
+
+fn self_modifying() -> PyResult<()> {
+    // TODO: add a self-modifying code check (where the previously-executed code is written to)
+
+    Ok(())
+}
+
+fn step_modify_rip() -> PyResult<()> {
+    let mut vm = new_vm(false)?;
+    vm.mem_map(0x100, 0x20, MemoryProtection::ExecuteRead)?;
+
+    // 0x100:  48 01 d8                add    rax,rbx
+    // 0x103:  48 83 e9 05             sub    rcx,0x5
+    // 0x107:  48 89 d9                mov    rcx,rbx
+    // 0x10a:  90                      nop
+    // 0x10b:  90                      nop
+    vm.mem_write(
+        0x100,
+        b"\x48\x01\xD8\x48\x83\xE9\x05\x48\x89\xD9\x90\x90\xCC".to_vec(),
+    )?;
+
+    vm.reg_write("rax", 0xF00)?;
+    vm.reg_write("rbx", 0x210)?;
+    vm.reg_write("rip", 0x100)?;
+
+    println!("starting run at {:#x}", vm.reg_read("rip")?);
+    let mut status = vm.step(1);
+
+    println!(
+        "ending run at {:#x} (status: {:?})",
+        vm.reg_read("rip")?,
+        status
+    );
+    vm.reg_write("rip", 0x100)?;
+    //vm.write_pc(0x100);
+    //println!("pc: {:#x}", vm.read_pc());
+    println!("rip rewritten {:#x}", vm.reg_read("rip")?);
+    status = vm.step(1);
+    println!(
+        "ending run at {:#x} (status: {:?})",
+        vm.reg_read("rip")?,
+        status
+    );
+
+    Ok(())
+}
+
+fn eflags_reconstruction() -> PyResult<()> {
+    let mut vm = new_vm(false)?;
+    vm.mem_map(0x100, 0x20, MemoryProtection::ExecuteRead)?;
+
+    vm.mem_write(0x100, b"\x48\x01\xD8\xCC".to_vec())?;
+    vm.reg_write("rax", 0x7FFFFFFFFFFFFFFF)?;
+    vm.reg_write("rbx", 0x1)?;
+
+    let of_mask = (1 << 11) as u64;
+
+    {
+        let eflags = vm.reg_read("eflags")?;
+        let of = vm.reg_read("OF")?;
+        let of_set = (eflags & of_mask) == of_mask;
+        println!("[pre] eflags: {:#x}, OF: {:#x} == {}", eflags, of, of_set);
+    }
+
+    vm.set_pc(0x100);
+    let status = vm.step(1);
+    println!("run status: {:?}", status);
+
+    {
+        let eflags = vm.reg_read("eflags")?;
+        let rflags = vm.reg_read("rflags")?;
+        let of = vm.reg_read("OF")?;
+        let of_set = (eflags & of_mask) == of_mask;
+        println!(
+            "[post] eflags: {:#x} == {:#x}, OF: {:#x} == {}",
+            eflags, rflags, of, of_set
+        );
+    }
+
+    {
+        vm.reg_write("OF", 0)?;
+        let eflags = vm.reg_read("eflags")?;
+        let of = vm.reg_read("OF")?;
+        let of_set = (eflags >> 11) & 1;
+        println!("[OF=0] eflags: {:#x}, OF: {:#x} == {}", eflags, of, of_set);
+    }
+
+    {
+        let mut eflags = vm.reg_read("eflags")?;
+        eflags |= of_mask;
+        vm.reg_write("rflags", eflags)?;
+        let of = vm.reg_read("OF")?;
+        let of_set = (eflags >> 11) & 1;
+        println!(
+            "[rflags|={:#x}] eflags: {:#x}, OF: {:#x} == {}",
+            of_mask, eflags, of, of_set
+        );
+    }
+
+    Ok(())
+}
+
+fn main() {
+    // Make sure the GHIDRA_SRC environment variable is valid
+    match std::env::var("GHIDRA_SRC") {
+        Ok(ghidra_src) => {
+            // Make sure the directory $GHIDRA_SRC/Ghidra/Processors exists
+            if !std::path::Path::new(&ghidra_src)
+                .join("Ghidra")
+                .join("Processors")
+                .exists()
+            {
+                println!("GHIDRA_SRC environment variable invalid!");
+                exit(1);
+            }
+            println!("GHIDRA_SRC: {}", ghidra_src);
+        }
+        Err(_) => {
+            println!("GHIDRA_SRC environment variable not set!");
+            exit(1);
+        }
+    }
+
+    let tests: Vec<(&str, fn() -> PyResult<()>)> = vec![
+        ("New i686", new_i686),
+        ("NX (block start)", nx_start),
+        ("NX (block middle)", nx_middle),
+        ("Invalid instruction (block start)", inv_start),
+        ("Invalid instruction (block middle)", inv_middle),
+        ("Block optimization bug", block_optimization),
+        ("Rewind", rewind),
+        ("Execute only", execute_only),
+        ("Execute uninitialized", execute_uninitialized),
+        ("Step modify rip", step_modify_rip),
+        ("EFlags reconstruction", eflags_reconstruction),
+    ];
+
+    let mut success = 0;
+    for (name, f) in tests.iter() {
+        println!("=== {} ===", name);
+        match f() {
+            Ok(_) => {
+                success += 1;
+                println!("[OK]");
+            }
+            Err(e) => {
+                println!("[ERROR] {}", e);
+            }
+        }
+    }
+
+    println!("{}/{} tests passed", success, tests.len());
+    exit(if success == tests.len() { 0 } else { 1 });
+}

tests/blockopt.py

@@ -0,0 +1,70 @@
+try:
+    xfail = __import__("pytest").mark.xfail(reason="Known broken")
+except ImportError:
+    xfail = lambda func: func
+
+from icicle import *
+
+"""
+issue: https://github.com/icicle-emu/icicle-emu/issues/64
+
+mchesser:
+Yeah, an assumption that the block optimizer makes is that there will be no external modifications to registers within a blocks. This issue can be reproduced with something as simple as:
+
+[4c 89 c9] "MOV RCX, R9"
+[49 89 c9] "MOV R9, RCX"
+Which optimizes to the following Pcode:
+
+<L0> (entry=0x0):
+	instruction(0x0)
+	RCX = R9
+	instruction(0x3)
+Without this assumption, it is essentially impossible to perform any optimization that cross instruction boundaries.
+
+That said there are a couple of ways that this could be made better:
+
+Disable block-level optimizations by default (or remove them completely) -- in general they don't actually help that much for performance and after 802ab0c, most of the optimizations should already be done by Cranelift, which affects full-block execution anyway.
+Only apply optimizations to the JIT-blocks, meaning the interpreter (which is what is used for single stepping) executes the unoptimized pcode. The emulator checks some preconditions to ensure that the block will either be executed to completion (or to some known exit points) before entering the JIT.
+Warn when "reg_write" is performed inside of a block when block-level optimizations are enabled.
+Automatically de-optimize the block if a manual reg-write is performed in it.
+Bypass the code-cache and disable optimizations when performing single stepping.
+Add more control over the optimization process (e.g. const-prop flags, but not GPRs).
+I'm thinking that (1.) is probably the best solution the near term. Currently the main reason for the block-level optimizations is to simplify some static analysis that occurs later in my other work (fuzzing) and make the pcode more "readable".
+
+However, I want to potentially move towards (2.) in the future to allow for more aggressive optimizations in certain cases.
+"""
+@xfail
+def test_blockopt():
+    emu = Icicle("x86_64", jit=True, optimize_block=True, tracing=True)
+
+    instructions = bytes.fromhex("41 C1 EA 07 41 83 E2 1F 74 08 44 89 D0 48 89 54 C6 08 49 83 C1 04 4C 89 0E 4C 89 C9 44 8B 11 44 89 D0 F7 D0 49 89 C9 A8 03 0F 84 88 F6 FF FF EB 4C".replace(" ", ""))
+
+    addr = 0x140001A73
+    heap = 0x71000
+    emu.mem_map(heap, 0x1000, MemoryProtection.ReadWrite)
+    emu.mem_write(heap + 4, 0x1337.to_bytes(4, "little"))
+    emu.mem_map(addr & ~0xFFF, 0x1000, MemoryProtection.ExecuteRead)
+    emu.mem_write(addr, instructions)
+    emu.reg_write("r9", heap)
+    emu.reg_write("r10", 0x13)
+    emu.reg_write("rip", addr)
+    emu.reg_write("rsi", heap + 0x100)
+
+    for i in range(11):
+        rip = emu.reg_read("rip")
+        rcx = emu.reg_read("rcx")
+        r9 = emu.reg_read("r9")
+        print(f"[{i}] RIP: {hex(rip)}, RCX: {hex(rcx)}, R9: {hex(r9)}")
+
+        if rip == 0x140001A8F:
+            emu.reg_write("r9", 0x13370900)
+
+        emu.step(1)
+
+        if rip == 0x140001A9A:
+            assert rcx == r9, f"expected rcx({hex(rcx)}) == r9({hex(r9)})"
+
+    print("Everything works!")
+
+if __name__ == "__main__":
+    test_blockopt()

tests/conftest.py

@@ -0,0 +1,9 @@
+import sys
+import pytest
+
+def pytest_collection_modifyitems(config, items):
+    if sys.platform == "darwin":
+        skip_macos = pytest.mark.skip(reason="Skipped on macOS")
+        for item in items:
+            if "example.py" in str(item.fspath):
+                item.add_marker(skip_macos)

tests/example.py

@@ -1,8 +1,7 @@
 import icicle
-import keystone
-import capstone
 
 def assemble(code: str, addr: int = 0) -> bytes:
+    import keystone
     ks = keystone.Ks(keystone.KS_ARCH_X86, keystone.KS_MODE_64)
     encoding, count = ks.asm(code, addr)
     if encoding is None:
@@ -10,6 +9,7 @@ def assemble(code: str, addr: int = 0) -> bytes:
     return bytes(encoding)
 
 def disassemble(code: bytes, addr: int = 0, max_count = 1000) -> str:
+    import capstone
     result = ""
     cs = capstone.Cs(capstone.CS_ARCH_X86, capstone.CS_MODE_64)
     count = 0
@@ -30,7 +30,7 @@ def disassemble(code: bytes, addr: int = 0, max_count = 1000) -> str:
             addr += size
     return result
 
-def old_test():
+def test_old():
     buf = assemble("mov eax, ebx\nnop")
     print(disassemble(buf, 0))
     print(assemble("mov eax, ebx").hex())
@@ -49,20 +49,18 @@ def old_test():
     vm.mem_map(addr, 0x1000, icicle.MemoryProtection.NoAccess)
     try:
         vm.mem_protect(addr, 0x2000, icicle.MemoryProtection.ExecuteRead)
-    except icicle.MemoryError as x:
-        print("MemoryError working!")
+    except icicle.MemoryException as x:
+        print("MemoryException working!")
         message = x.args[0]
         print(message, x.code)
     except Exception as x:
-        print(x, type(x), isinstance(x, icicle.MemoryError))
+        print(x, type(x), isinstance(x, icicle.MemoryException))
     vm.mem_protect(addr, 0x1000, icicle.MemoryProtection.ExecuteRead)
     vm.mem_write(addr, b"\x90\x90\x90")
     data = vm.mem_read(addr, 4)
     print(data, type(data))
 
-def main():
-    old_test()
-
+def test_new():
     print("")
     vm = icicle.Icicle("x86_64", jit=False)
     print(vm)
@@ -91,5 +89,9 @@ nop
         print(f"rax: {hex(vm.reg_read('rax'))}")
         assert False, "Should be unreachable"
 
+def main():
+    test_old()
+    test_new()
+
 if __name__ == "__main__":
     main()

tests/hlt.py

@@ -0,0 +1,17 @@
+from icicle import *
+
+def hlt():
+    vm = Icicle("x86_64", jit=False, tracing=True)
+    page = 0x10000
+    vm.mem_map(page, 0x1000, MemoryProtection.ExecuteRead)
+    vm.mem_write(page, b"\xF4\xEB\xFE")
+    vm.reg_write("rip", page)
+    status = vm.step(1000)
+    print(status, vm.exception_code)
+    print(hex(vm.reg_read("rip")))
+
+def main():
+    hlt()
+
+if __name__ == "__main__":
+    main()

tests/invalid.py

@@ -9,7 +9,7 @@ Scenarios:
 
 from icicle import *
 
-def nx():
+def test_nx():
     vm = Icicle("x86_64", jit=False)
     page = 0x10000
     vm.mem_map(page, 0x1000, MemoryProtection.ReadOnly)
@@ -22,7 +22,7 @@ def nx():
     assert vm.exception_code == ExceptionCode.ExecViolation
     assert vm.exception_value == page
 
-def inv_start():
+def test_inv_start():
     vm = Icicle("x86_64", jit=False)
     page = 0x10000
     vm.mem_map(page, 0x1000, MemoryProtection.ExecuteRead)
@@ -35,7 +35,7 @@ def inv_start():
     assert vm.exception_code == ExceptionCode.InvalidInstruction
     assert vm.exception_value == page
 
-def inv_middle():
+def test_inv_middle():
     vm = Icicle("x86_64", jit=False)
     page = 0x10000
     vm.mem_map(page, 0x1000, MemoryProtection.ExecuteRead)
@@ -50,11 +50,11 @@ def inv_middle():
 
 def main():
     print("=== NX ===")
-    nx()
+    test_nx()
     print("=== Invalid instruction (block start) ===")
-    inv_start()
+    test_inv_start()
     print("=== Invalid instruction (block middle) ===")
-    inv_middle()
+    test_inv_middle()
     print("\nSUCCESS")
 
 if __name__ == "__main__":

tests/issue32.py

@@ -0,0 +1,35 @@
+# https://github.com/icicle-emu/icicle-python/issues/32
+from icicle import Icicle, MemoryProtection, RunStatus, ExceptionCode
+
+def test_memhook():
+    data = bytes.fromhex(
+        "A1 FF FF 01 00"        # mov     eax, [0x1FFFF]
+        "B8 02 00 00 00"        # mov     eax, 2
+        "66 A3 A0 B3 01 10"     # mov     [0x1001B3A0], ax
+    )
+
+    ice = Icicle("i686")
+    ice.mem_map(0, 0x100, MemoryProtection.ExecuteOnly)
+    ice.mem_write(0, data)
+    status = ice.step(1)
+    assert status == RunStatus.UnhandledException
+    assert ice.exception_code == ExceptionCode.ReadUnmapped
+    assert ice.reg_read("eip") == 0
+
+    ice.mem_map(0x10000, 0x20000, MemoryProtection.ExecuteOnly)
+    status = ice.step(1)
+    assert status == RunStatus.UnhandledException
+    assert ice.exception_code == ExceptionCode.ReadPerm
+    assert ice.reg_read("eip") == 0
+
+    ice.mem_protect(0x1FFFF, 4, MemoryProtection.ExecuteReadWrite)
+    status = ice.step(1)
+    assert status == RunStatus.InstructionLimit
+
+    assert ice.reg_read("eip") == 5
+    assert ice.reg_read("eax") == 0
+
+    print("SUCCESS")
+
+if __name__ == "__main__":
+    test_memhook()

tests/requirements.txt

@@ -1,2 +0,0 @@
-keystone-engine==0.9.2
-capstone==4.0.2

uv.lock

@@ -0,0 +1,297 @@
+version = 1
+revision = 2
+requires-python = ">=3.8"
+resolution-markers = [
+    "python_full_version >= '3.9'",
+    "python_full_version < '3.9'",
+]
+
+[[package]]
+name = "capstone"
+version = "5.0.6"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "importlib-resources", marker = "python_full_version < '3.9'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d5/b0/1f126035a4cbc6f488b97e4bd57a46a28b6ba29ca8b938cbda840601a18a/capstone-5.0.6.tar.gz", hash = "sha256:b11a87d67751b006b9b44428d59c99512e6d6c89cf7dff8cdd92d9065628b5a0", size = 2945704, upload-time = "2025-03-23T16:03:40.795Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cd/9a/d9c11e090fa03dfc61a03a57ba44c6a07370f4ac5814f2a5804bfd40ee8b/capstone-5.0.6-py3-none-macosx_10_9_universal2.whl", hash = "sha256:0bca16e1c3ca1b928df6103b3889dcb6df7b05392d75a0b7af3508798148b899", size = 2177082, upload-time = "2025-03-23T16:03:27.815Z" },
+    { url = "https://files.pythonhosted.org/packages/66/28/72a0be2325e6ee459f27cdcd835d3eee6fed5136321b5f7be41b41dc8656/capstone-5.0.6-py3-none-macosx_10_9_x86_64.whl", hash = "sha256:539191906a34ad1c573ec12b787b2caf154ea41175db6ded9def00aea8151099", size = 1180215, upload-time = "2025-03-23T16:03:29.409Z" },
+    { url = "https://files.pythonhosted.org/packages/54/93/7b8fb02661d47a2822d5b640df804ef310417144af02e6db3446f174c4b5/capstone-5.0.6-py3-none-macosx_11_0_arm64.whl", hash = "sha256:e0b87b283905e4fc43635ca04cf26f4a5d9e8375852e5464d38938f3a28c207a", size = 1192757, upload-time = "2025-03-23T16:03:30.966Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/a2/d1bdb7260ade8165182979ea16098ef3a37c01316140511a611e549dbfe3/capstone-5.0.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:fa7892f0c89455078c18f07d2d309fb07baa53061b8f9a63db1ea00d41a46726", size = 1458413, upload-time = "2025-03-23T16:03:32.04Z" },
+    { url = "https://files.pythonhosted.org/packages/78/7f/ec0687bbe8f6b128f1d41d90ec7cedfd1aaaa4ecb1ae8d334acc7dad8013/capstone-5.0.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0358855773100bb91ae6681fabce7299df83156945ba943f6211061a592c54a6", size = 1481605, upload-time = "2025-03-23T16:03:33.526Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/1d/77bb0f79e1dacdfdcc0679c747d9ca24cc621095e09bdb665e7dd0c580ae/capstone-5.0.6-py3-none-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:667d6466dab1522fa5e9659be5cf1aca83e4fc3da7d15d0e5e6047f71fb46c4a", size = 1480730, upload-time = "2025-03-23T16:03:34.601Z" },
+    { url = "https://files.pythonhosted.org/packages/72/63/07437972f68d0b2ba13e1705a6994404c9c961afbadc342c5b6fcf1de652/capstone-5.0.6-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:45c0e25500dd8d283d3b70f2e10cebfec93ab8bdaf6af9a763a0a999b4705891", size = 1457992, upload-time = "2025-03-23T16:03:35.75Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/53/f371e86493a2ae659b5a493c3cc23122974e83a1f53d3a5638d7bb7ac371/capstone-5.0.6-py3-none-musllinux_1_2_i686.whl", hash = "sha256:22f1f2f118f8fa1d1c5c90bca90e75864d55e16349b3c03aaea0e86b4a45d2a9", size = 1484184, upload-time = "2025-03-23T16:03:37.05Z" },
+    { url = "https://files.pythonhosted.org/packages/df/c3/8b842ae32949c3570581164619c2f69001c6d8da566dc2e490372032b0d6/capstone-5.0.6-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:bc23cf634f51d0e53bdd04ea53ccfff7fc9060dfe58dff1e1b260ce40e5538ff", size = 1485357, upload-time = "2025-03-23T16:03:38.133Z" },
+    { url = "https://files.pythonhosted.org/packages/da/72/ff7894c2fb5716d9a3ce9c27ba34b29d991a11d8442d2ef0fcdc5564ba7e/capstone-5.0.6-py3-none-win_amd64.whl", hash = "sha256:761c3deae00b22ac697081cdae1383bb90659dd0d79387a09cf5bdbb22b17064", size = 1271345, upload-time = "2025-03-23T16:03:39.649Z" },
+]
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
+]
+
+[[package]]
+name = "exceptiongroup"
+version = "1.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions", version = "4.13.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.9'" },
+    { name = "typing-extensions", version = "4.15.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.9' and python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0b/9f/a65090624ecf468cdca03533906e7c69ed7588582240cfe7cc9e770b50eb/exceptiongroup-1.3.0.tar.gz", hash = "sha256:b241f5885f560bc56a59ee63ca4c6a8bfa46ae4ad651af316d4e81817bb9fd88", size = 29749, upload-time = "2025-05-10T17:42:51.123Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/36/f4/c6e662dade71f56cd2f3735141b265c3c79293c109549c1e6933b0651ffc/exceptiongroup-1.3.0-py3-none-any.whl", hash = "sha256:4d111e6e0c13d0644cad6ddaa7ed0261a0b36971f6d23e7ec9b4b9097da78a10", size = 16674, upload-time = "2025-05-10T17:42:49.33Z" },
+]
+
+[[package]]
+name = "icicle-emu"
+version = "1.0.0"
+source = { editable = "." }
+
+[package.dev-dependencies]
+dev = [
+    { name = "capstone" },
+    { name = "keystone-engine" },
+    { name = "maturin" },
+    { name = "pytest", version = "8.3.5", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.9'" },
+    { name = "pytest", version = "8.4.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.9'" },
+]
+
+[package.metadata]
+
+[package.metadata.requires-dev]
+dev = [
+    { name = "capstone", specifier = ">=5.0.6" },
+    { name = "keystone-engine", specifier = ">=0.9.2" },
+    { name = "maturin", specifier = ">=1.7.8" },
+    { name = "pytest", specifier = ">=8.3.3" },
+]
+
+[[package]]
+name = "importlib-resources"
+version = "6.4.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "zipp", marker = "python_full_version < '3.9'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/98/be/f3e8c6081b684f176b761e6a2fef02a0be939740ed6f54109a2951d806f3/importlib_resources-6.4.5.tar.gz", hash = "sha256:980862a1d16c9e147a59603677fa2aa5fd82b87f223b6cb870695bcfce830065", size = 43372, upload-time = "2024-09-09T17:03:14.677Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e1/6a/4604f9ae2fa62ef47b9de2fa5ad599589d28c9fd1d335f32759813dfa91e/importlib_resources-6.4.5-py3-none-any.whl", hash = "sha256:ac29d5f956f01d5e4bb63102a5a19957f1b9175e45649977264a1416783bb717", size = 36115, upload-time = "2024-09-09T17:03:13.39Z" },
+]
+
+[[package]]
+name = "iniconfig"
+version = "2.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f2/97/ebf4da567aa6827c909642694d71c9fcf53e5b504f2d96afea02718862f3/iniconfig-2.1.0.tar.gz", hash = "sha256:3abbd2e30b36733fee78f9c7f7308f2d0050e88f0087fd25c2645f63c773e1c7", size = 4793, upload-time = "2025-03-19T20:09:59.721Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2c/e1/e6716421ea10d38022b952c159d5161ca1193197fb744506875fbb87ea7b/iniconfig-2.1.0-py3-none-any.whl", hash = "sha256:9deba5723312380e77435581c6bf4935c94cbfab9b1ed33ef8d238ea168eb760", size = 6050, upload-time = "2025-03-19T20:10:01.071Z" },
+]
+
+[[package]]
+name = "keystone-engine"
+version = "0.9.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/0a/65/3a2e7e55cc1db188869bbbacee60036828330e0ce57fc5f05a3167ab4b4d/keystone-engine-0.9.2.tar.gz", hash = "sha256:2f7af62dab0ce6c2732dbb4f31cfa2184a8a149e280b96b92ebc0db84c6e50f5", size = 2813059, upload-time = "2020-06-21T14:13:59.951Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1c/ad/a609493a534049cae43660689b2c5908117746e238f12dc76619d68a223a/keystone_engine-0.9.2-py2.py3-none-macosx_10_14_x86_64.whl", hash = "sha256:dafcc3d9450c239cbc54148855b79c4b387777099c6d054005c835768cf955f2", size = 2950758, upload-time = "2020-06-21T14:13:53.225Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/cf/b8eb6956565e91a9a003b1c612765cfe007a1d0b1c6e667dc569ea519f51/keystone_engine-0.9.2-py2.py3-none-manylinux1_i686.whl", hash = "sha256:9e04dea5a2b50509b7b707abdb395de42772c40faa36131ea94482fba8dd5d9f", size = 1785427, upload-time = "2020-06-21T14:13:54.624Z" },
+    { url = "https://files.pythonhosted.org/packages/01/5c/40ffbec589262f49ff7c463d96ff0bfab0fbd98d9d869c370a70853a13fb/keystone_engine-0.9.2-py2.py3-none-manylinux1_x86_64.whl", hash = "sha256:5a5316a34323620b1bba31dcfe9e4b4ca6f0c030e82fc7a151da7c8fbe81a379", size = 1766182, upload-time = "2020-06-21T14:13:55.817Z" },
+    { url = "https://files.pythonhosted.org/packages/88/b9/a9d8b6837346b86bcdda56e5c3fe4ac51f98f4ed40bf71fb6bd8605516da/keystone_engine-0.9.2-py2.py3-none-win32.whl", hash = "sha256:9f81e480904a405ef008f1d9f0e4a05e37d2bd83c5218a27136e1a294b02c1f6", size = 1318239, upload-time = "2020-06-21T14:13:57.122Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/8d/58471cb026de45397b29ba4b37ae3e20b434fae14c4b92fd3e9771a7bac8/keystone_engine-0.9.2-py2.py3-none-win_amd64.whl", hash = "sha256:c91db1ff16d9d094e00d1827107d1b4afd5e63ce19b491a0140e660635000e8b", size = 1370823, upload-time = "2020-06-21T14:13:58.476Z" },
+]
+
+[[package]]
+name = "maturin"
+version = "1.9.6"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "tomli", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/9a/35/c3370188492f4c139c7a318f438d01b8185c216303c49c4bc885c98b6afb/maturin-1.9.6.tar.gz", hash = "sha256:2c2ae37144811d365509889ed7220b0598487f1278c2441829c3abf56cc6324a", size = 214846, upload-time = "2025-10-07T12:45:08.408Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/55/5c/b435418ba4ba2647a1f7a95d53314991b1e556e656ae276dea993c3bce1d/maturin-1.9.6-py3-none-linux_armv6l.whl", hash = "sha256:26e3ab1a42a7145824210e9d763f6958f2c46afb1245ddd0bab7d78b1f59bb3f", size = 8134483, upload-time = "2025-10-07T12:44:44.274Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/1c/8e58eda6601f328b412cdeeaa88a9b6a10e591e2a73f313e8c0154d68385/maturin-1.9.6-py3-none-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl", hash = "sha256:5263dda3f71feef2e4122baf5c4620e4b3710dbb7f2121f85a337182de214369", size = 15776470, upload-time = "2025-10-07T12:44:47.476Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/33/8c967cce6848cdd87a2e442c86120ac644b80c5ed4c32e3291bde6a17df8/maturin-1.9.6-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:fe78262c2800c92f67d1ce3c0f6463f958a692cc67bfb572e5dbf5b4b696a8ba", size = 8226557, upload-time = "2025-10-07T12:44:49.844Z" },
+    { url = "https://files.pythonhosted.org/packages/58/bd/3e2675cdc8b7270700ba30c663c852a35694441732a107ac30ebd6878bd8/maturin-1.9.6-py3-none-manylinux_2_12_i686.manylinux2010_i686.musllinux_1_1_i686.whl", hash = "sha256:7ab827c6e8c022eb2e1e7fb6deede54549c8460b20ccc2e9268cc6e8cde957a8", size = 8166544, upload-time = "2025-10-07T12:44:51.396Z" },
+    { url = "https://files.pythonhosted.org/packages/58/1f/a2047ddf2230e700d5f8a13dd4b9af5ce806ad380c32e58105888205926e/maturin-1.9.6-py3-none-manylinux_2_12_x86_64.manylinux2010_x86_64.musllinux_1_1_x86_64.whl", hash = "sha256:0246202377c49449315305209f45c8ecef6e2d6bd27a04b5b6f1ab3e4ea47238", size = 8641010, upload-time = "2025-10-07T12:44:53.658Z" },
+    { url = "https://files.pythonhosted.org/packages/be/1f/265d63c7aa6faf363d4a3f23396f51bc6b4d5c7680a4190ae68dba25dea2/maturin-1.9.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_1_aarch64.whl", hash = "sha256:f5bac167700fbb6f8c8ed1a97b494522554b4432d7578e11403b894b6a91d99f", size = 7965945, upload-time = "2025-10-07T12:44:55.248Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/ca/a8e61979ccfe080948bcc1bddd79356157aee687134df7fb013050cec783/maturin-1.9.6-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.musllinux_1_1_armv7l.whl", hash = "sha256:7f53d3b1d8396d3fea3e1ee5fd37558bca5719090f3d194ba1c02b0b56327ae3", size = 7978820, upload-time = "2025-10-07T12:44:56.919Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/4a/81b412f8ad02a99801ef19ec059fba0822d1d28fb44cb6a92e722f05f278/maturin-1.9.6-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.musllinux_1_1_ppc64le.whl", hash = "sha256:7f506eb358386d94d6ec3208c003130cf4b69cab26034fc0cbbf8bf83afa4c2e", size = 10452064, upload-time = "2025-10-07T12:44:58.232Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/12/cc96c7a8cb51d8dcc9badd886c361caa1526fba7fa69d1e7892e613b71d4/maturin-1.9.6-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:f2d6984ab690af509f525dbd2b130714207c06ebb14a5814edbe1e42b17ae0de", size = 8852401, upload-time = "2025-10-07T12:44:59.8Z" },
+    { url = "https://files.pythonhosted.org/packages/51/8e/653ac3c9f2c25cdd81aefb0a2d17ff140ca5a14504f5e3c7f94dcfe4dbb7/maturin-1.9.6-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:5c2252b0956bb331460ac750c805ddf0d9b44442449fc1f16e3b66941689d0bc", size = 8425057, upload-time = "2025-10-07T12:45:01.711Z" },
+    { url = "https://files.pythonhosted.org/packages/db/29/f13490328764ae9bfc1da55afc5b707cebe4fa75ad7a1573bfa82cfae0c6/maturin-1.9.6-py3-none-win32.whl", hash = "sha256:f2c58d29ebdd4346fd004e6be213d071fdd94a77a16aa91474a21a4f9dbf6309", size = 7165956, upload-time = "2025-10-07T12:45:03.766Z" },
+    { url = "https://files.pythonhosted.org/packages/db/9f/dd51e5ac1fce47581b8efa03d77a03f928c0ef85b6e48a61dfa37b6b85a2/maturin-1.9.6-py3-none-win_amd64.whl", hash = "sha256:1b39a5d82572c240d20d9e8be024d722dfb311d330c5e28ddeb615211755941a", size = 8145722, upload-time = "2025-10-07T12:45:05.487Z" },
+    { url = "https://files.pythonhosted.org/packages/65/f2/e97aaba6d0d78c5871771bf9dd71d4eb8dac15df9109cf452748d2207412/maturin-1.9.6-py3-none-win_arm64.whl", hash = "sha256:ac02a30083553d2a781c10cd6f5480119bf6692fd177e743267406cad2ad198c", size = 6857006, upload-time = "2025-10-07T12:45:06.813Z" },
+]
+
+[[package]]
+name = "packaging"
+version = "25.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a1/d4/1fc4078c65507b51b96ca8f8c3ba19e6a61c8253c72794544580a7b6c24d/packaging-25.0.tar.gz", hash = "sha256:d443872c98d677bf60f6a1f2f8c1cb748e8fe762d2bf9d3148b5599295b0fc4f", size = 165727, upload-time = "2025-04-19T11:48:59.673Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/20/12/38679034af332785aac8774540895e234f4d07f7545804097de4b666afd8/packaging-25.0-py3-none-any.whl", hash = "sha256:29572ef2b1f17581046b3a2227d5c611fb25ec70ca1ba8554b24b0e69331a484", size = 66469, upload-time = "2025-04-19T11:48:57.875Z" },
+]
+
+[[package]]
+name = "pluggy"
+version = "1.5.0"
+source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+    "python_full_version < '3.9'",
+]
+sdist = { url = "https://files.pythonhosted.org/packages/96/2d/02d4312c973c6050a18b314a5ad0b3210edb65a906f868e31c111dede4a6/pluggy-1.5.0.tar.gz", hash = "sha256:2cffa88e94fdc978c4c574f15f9e59b7f4201d439195c3715ca9e2486f1d0cf1", size = 67955, upload-time = "2024-04-20T21:34:42.531Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/88/5f/e351af9a41f866ac3f1fac4ca0613908d9a41741cfcf2228f4ad853b697d/pluggy-1.5.0-py3-none-any.whl", hash = "sha256:44e1ad92c8ca002de6377e165f3e0f1be63266ab4d554740532335b9d75ea669", size = 20556, upload-time = "2024-04-20T21:34:40.434Z" },
+]
+
+[[package]]
+name = "pluggy"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+    "python_full_version >= '3.9'",
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412, upload-time = "2025-05-15T12:30:07.975Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.19.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b0/77/a5b8c569bf593b0140bde72ea885a803b82086995367bf2037de0159d924/pygments-2.19.2.tar.gz", hash = "sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887", size = 4968631, upload-time = "2025-06-21T13:39:12.283Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" },
+]
+
+[[package]]
+name = "pytest"
+version = "8.3.5"
+source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+    "python_full_version < '3.9'",
+]
+dependencies = [
+    { name = "colorama", marker = "python_full_version < '3.9' and sys_platform == 'win32'" },
+    { name = "exceptiongroup", marker = "python_full_version < '3.9'" },
+    { name = "iniconfig", marker = "python_full_version < '3.9'" },
+    { name = "packaging", marker = "python_full_version < '3.9'" },
+    { name = "pluggy", version = "1.5.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.9'" },
+    { name = "tomli", marker = "python_full_version < '3.9'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ae/3c/c9d525a414d506893f0cd8a8d0de7706446213181570cdbd766691164e40/pytest-8.3.5.tar.gz", hash = "sha256:f4efe70cc14e511565ac476b57c279e12a855b11f48f212af1080ef2263d3845", size = 1450891, upload-time = "2025-03-02T12:54:54.503Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/30/3d/64ad57c803f1fa1e963a7946b6e0fea4a70df53c1a7fed304586539c2bac/pytest-8.3.5-py3-none-any.whl", hash = "sha256:c69214aa47deac29fad6c2a4f590b9c4a9fdb16a403176fe154b79c0b4d4d820", size = 343634, upload-time = "2025-03-02T12:54:52.069Z" },
+]
+
+[[package]]
+name = "pytest"
+version = "8.4.2"
+source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+    "python_full_version >= '3.9'",
+]
+dependencies = [
+    { name = "colorama", marker = "python_full_version >= '3.9' and sys_platform == 'win32'" },
+    { name = "exceptiongroup", marker = "python_full_version >= '3.9' and python_full_version < '3.11'" },
+    { name = "iniconfig", marker = "python_full_version >= '3.9'" },
+    { name = "packaging", marker = "python_full_version >= '3.9'" },
+    { name = "pluggy", version = "1.6.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.9'" },
+    { name = "pygments", marker = "python_full_version >= '3.9'" },
+    { name = "tomli", marker = "python_full_version >= '3.9' and python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a3/5c/00a0e072241553e1a7496d638deababa67c5058571567b92a7eaa258397c/pytest-8.4.2.tar.gz", hash = "sha256:86c0d0b93306b961d58d62a4db4879f27fe25513d4b969df351abdddb3c30e01", size = 1519618, upload-time = "2025-09-04T14:34:22.711Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a8/a4/20da314d277121d6534b3a980b29035dcd51e6744bd79075a6ce8fa4eb8d/pytest-8.4.2-py3-none-any.whl", hash = "sha256:872f880de3fc3a5bdc88a11b39c9710c3497a547cfa9320bc3c5e62fbf272e79", size = 365750, upload-time = "2025-09-04T14:34:20.226Z" },
+]
+
+[[package]]
+name = "tomli"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/52/ed/3f73f72945444548f33eba9a87fc7a6e969915e7b1acc8260b30e1f76a2f/tomli-2.3.0.tar.gz", hash = "sha256:64be704a875d2a59753d80ee8a533c3fe183e3f06807ff7dc2232938ccb01549", size = 17392, upload-time = "2025-10-08T22:01:47.119Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/2e/299f62b401438d5fe1624119c723f5d877acc86a4c2492da405626665f12/tomli-2.3.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:88bd15eb972f3664f5ed4b57c1634a97153b4bac4479dcb6a495f41921eb7f45", size = 153236, upload-time = "2025-10-08T22:01:00.137Z" },
+    { url = "https://files.pythonhosted.org/packages/86/7f/d8fffe6a7aefdb61bced88fcb5e280cfd71e08939da5894161bd71bea022/tomli-2.3.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:883b1c0d6398a6a9d29b508c331fa56adbcdff647f6ace4dfca0f50e90dfd0ba", size = 148084, upload-time = "2025-10-08T22:01:01.63Z" },
+    { url = "https://files.pythonhosted.org/packages/47/5c/24935fb6a2ee63e86d80e4d3b58b222dafaf438c416752c8b58537c8b89a/tomli-2.3.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d1381caf13ab9f300e30dd8feadb3de072aeb86f1d34a8569453ff32a7dea4bf", size = 234832, upload-time = "2025-10-08T22:01:02.543Z" },
+    { url = "https://files.pythonhosted.org/packages/89/da/75dfd804fc11e6612846758a23f13271b76d577e299592b4371a4ca4cd09/tomli-2.3.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a0e285d2649b78c0d9027570d4da3425bdb49830a6156121360b3f8511ea3441", size = 242052, upload-time = "2025-10-08T22:01:03.836Z" },
+    { url = "https://files.pythonhosted.org/packages/70/8c/f48ac899f7b3ca7eb13af73bacbc93aec37f9c954df3c08ad96991c8c373/tomli-2.3.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:0a154a9ae14bfcf5d8917a59b51ffd5a3ac1fd149b71b47a3a104ca4edcfa845", size = 239555, upload-time = "2025-10-08T22:01:04.834Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/28/72f8afd73f1d0e7829bfc093f4cb98ce0a40ffc0cc997009ee1ed94ba705/tomli-2.3.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:74bf8464ff93e413514fefd2be591c3b0b23231a77f901db1eb30d6f712fc42c", size = 245128, upload-time = "2025-10-08T22:01:05.84Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/eb/a7679c8ac85208706d27436e8d421dfa39d4c914dcf5fa8083a9305f58d9/tomli-2.3.0-cp311-cp311-win32.whl", hash = "sha256:00b5f5d95bbfc7d12f91ad8c593a1659b6387b43f054104cda404be6bda62456", size = 96445, upload-time = "2025-10-08T22:01:06.896Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/fe/3d3420c4cb1ad9cb462fb52967080575f15898da97e21cb6f1361d505383/tomli-2.3.0-cp311-cp311-win_amd64.whl", hash = "sha256:4dc4ce8483a5d429ab602f111a93a6ab1ed425eae3122032db7e9acf449451be", size = 107165, upload-time = "2025-10-08T22:01:08.107Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/b7/40f36368fcabc518bb11c8f06379a0fd631985046c038aca08c6d6a43c6e/tomli-2.3.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:d7d86942e56ded512a594786a5ba0a5e521d02529b3826e7761a05138341a2ac", size = 154891, upload-time = "2025-10-08T22:01:09.082Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/3f/d9dd692199e3b3aab2e4e4dd948abd0f790d9ded8cd10cbaae276a898434/tomli-2.3.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:73ee0b47d4dad1c5e996e3cd33b8a76a50167ae5f96a2607cbe8cc773506ab22", size = 148796, upload-time = "2025-10-08T22:01:10.266Z" },
+    { url = "https://files.pythonhosted.org/packages/60/83/59bff4996c2cf9f9387a0f5a3394629c7efa5ef16142076a23a90f1955fa/tomli-2.3.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:792262b94d5d0a466afb5bc63c7daa9d75520110971ee269152083270998316f", size = 242121, upload-time = "2025-10-08T22:01:11.332Z" },
+    { url = "https://files.pythonhosted.org/packages/45/e5/7c5119ff39de8693d6baab6c0b6dcb556d192c165596e9fc231ea1052041/tomli-2.3.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4f195fe57ecceac95a66a75ac24d9d5fbc98ef0962e09b2eddec5d39375aae52", size = 250070, upload-time = "2025-10-08T22:01:12.498Z" },
+    { url = "https://files.pythonhosted.org/packages/45/12/ad5126d3a278f27e6701abde51d342aa78d06e27ce2bb596a01f7709a5a2/tomli-2.3.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:e31d432427dcbf4d86958c184b9bfd1e96b5b71f8eb17e6d02531f434fd335b8", size = 245859, upload-time = "2025-10-08T22:01:13.551Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/a1/4d6865da6a71c603cfe6ad0e6556c73c76548557a8d658f9e3b142df245f/tomli-2.3.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:7b0882799624980785240ab732537fcfc372601015c00f7fc367c55308c186f6", size = 250296, upload-time = "2025-10-08T22:01:14.614Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/b7/a7a7042715d55c9ba6e8b196d65d2cb662578b4d8cd17d882d45322b0d78/tomli-2.3.0-cp312-cp312-win32.whl", hash = "sha256:ff72b71b5d10d22ecb084d345fc26f42b5143c5533db5e2eaba7d2d335358876", size = 97124, upload-time = "2025-10-08T22:01:15.629Z" },
+    { url = "https://files.pythonhosted.org/packages/06/1e/f22f100db15a68b520664eb3328fb0ae4e90530887928558112c8d1f4515/tomli-2.3.0-cp312-cp312-win_amd64.whl", hash = "sha256:1cb4ed918939151a03f33d4242ccd0aa5f11b3547d0cf30f7c74a408a5b99878", size = 107698, upload-time = "2025-10-08T22:01:16.51Z" },
+    { url = "https://files.pythonhosted.org/packages/89/48/06ee6eabe4fdd9ecd48bf488f4ac783844fd777f547b8d1b61c11939974e/tomli-2.3.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:5192f562738228945d7b13d4930baffda67b69425a7f0da96d360b0a3888136b", size = 154819, upload-time = "2025-10-08T22:01:17.964Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/01/88793757d54d8937015c75dcdfb673c65471945f6be98e6a0410fba167ed/tomli-2.3.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:be71c93a63d738597996be9528f4abe628d1adf5e6eb11607bc8fe1a510b5dae", size = 148766, upload-time = "2025-10-08T22:01:18.959Z" },
+    { url = "https://files.pythonhosted.org/packages/42/17/5e2c956f0144b812e7e107f94f1cc54af734eb17b5191c0bbfb72de5e93e/tomli-2.3.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c4665508bcbac83a31ff8ab08f424b665200c0e1e645d2bd9ab3d3e557b6185b", size = 240771, upload-time = "2025-10-08T22:01:20.106Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/f4/0fbd014909748706c01d16824eadb0307115f9562a15cbb012cd9b3512c5/tomli-2.3.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4021923f97266babc6ccab9f5068642a0095faa0a51a246a6a02fccbb3514eaf", size = 248586, upload-time = "2025-10-08T22:01:21.164Z" },
+    { url = "https://files.pythonhosted.org/packages/30/77/fed85e114bde5e81ecf9bc5da0cc69f2914b38f4708c80ae67d0c10180c5/tomli-2.3.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:a4ea38c40145a357d513bffad0ed869f13c1773716cf71ccaa83b0fa0cc4e42f", size = 244792, upload-time = "2025-10-08T22:01:22.417Z" },
+    { url = "https://files.pythonhosted.org/packages/55/92/afed3d497f7c186dc71e6ee6d4fcb0acfa5f7d0a1a2878f8beae379ae0cc/tomli-2.3.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:ad805ea85eda330dbad64c7ea7a4556259665bdf9d2672f5dccc740eb9d3ca05", size = 248909, upload-time = "2025-10-08T22:01:23.859Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/84/ef50c51b5a9472e7265ce1ffc7f24cd4023d289e109f669bdb1553f6a7c2/tomli-2.3.0-cp313-cp313-win32.whl", hash = "sha256:97d5eec30149fd3294270e889b4234023f2c69747e555a27bd708828353ab606", size = 96946, upload-time = "2025-10-08T22:01:24.893Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/b7/718cd1da0884f281f95ccfa3a6cc572d30053cba64603f79d431d3c9b61b/tomli-2.3.0-cp313-cp313-win_amd64.whl", hash = "sha256:0c95ca56fbe89e065c6ead5b593ee64b84a26fca063b5d71a1122bf26e533999", size = 107705, upload-time = "2025-10-08T22:01:26.153Z" },
+    { url = "https://files.pythonhosted.org/packages/19/94/aeafa14a52e16163008060506fcb6aa1949d13548d13752171a755c65611/tomli-2.3.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:cebc6fe843e0733ee827a282aca4999b596241195f43b4cc371d64fc6639da9e", size = 154244, upload-time = "2025-10-08T22:01:27.06Z" },
+    { url = "https://files.pythonhosted.org/packages/db/e4/1e58409aa78eefa47ccd19779fc6f36787edbe7d4cd330eeeedb33a4515b/tomli-2.3.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:4c2ef0244c75aba9355561272009d934953817c49f47d768070c3c94355c2aa3", size = 148637, upload-time = "2025-10-08T22:01:28.059Z" },
+    { url = "https://files.pythonhosted.org/packages/26/b6/d1eccb62f665e44359226811064596dd6a366ea1f985839c566cd61525ae/tomli-2.3.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c22a8bf253bacc0cf11f35ad9808b6cb75ada2631c2d97c971122583b129afbc", size = 241925, upload-time = "2025-10-08T22:01:29.066Z" },
+    { url = "https://files.pythonhosted.org/packages/70/91/7cdab9a03e6d3d2bb11beae108da5bdc1c34bdeb06e21163482544ddcc90/tomli-2.3.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0eea8cc5c5e9f89c9b90c4896a8deefc74f518db5927d0e0e8d4a80953d774d0", size = 249045, upload-time = "2025-10-08T22:01:31.98Z" },
+    { url = "https://files.pythonhosted.org/packages/15/1b/8c26874ed1f6e4f1fcfeb868db8a794cbe9f227299402db58cfcc858766c/tomli-2.3.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:b74a0e59ec5d15127acdabd75ea17726ac4c5178ae51b85bfe39c4f8a278e879", size = 245835, upload-time = "2025-10-08T22:01:32.989Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/42/8e3c6a9a4b1a1360c1a2a39f0b972cef2cc9ebd56025168c4137192a9321/tomli-2.3.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:b5870b50c9db823c595983571d1296a6ff3e1b88f734a4c8f6fc6188397de005", size = 253109, upload-time = "2025-10-08T22:01:34.052Z" },
+    { url = "https://files.pythonhosted.org/packages/22/0c/b4da635000a71b5f80130937eeac12e686eefb376b8dee113b4a582bba42/tomli-2.3.0-cp314-cp314-win32.whl", hash = "sha256:feb0dacc61170ed7ab602d3d972a58f14ee3ee60494292d384649a3dc38ef463", size = 97930, upload-time = "2025-10-08T22:01:35.082Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/74/cb1abc870a418ae99cd5c9547d6bce30701a954e0e721821df483ef7223c/tomli-2.3.0-cp314-cp314-win_amd64.whl", hash = "sha256:b273fcbd7fc64dc3600c098e39136522650c49bca95df2d11cf3b626422392c8", size = 107964, upload-time = "2025-10-08T22:01:36.057Z" },
+    { url = "https://files.pythonhosted.org/packages/54/78/5c46fff6432a712af9f792944f4fcd7067d8823157949f4e40c56b8b3c83/tomli-2.3.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:940d56ee0410fa17ee1f12b817b37a4d4e4dc4d27340863cc67236c74f582e77", size = 163065, upload-time = "2025-10-08T22:01:37.27Z" },
+    { url = "https://files.pythonhosted.org/packages/39/67/f85d9bd23182f45eca8939cd2bc7050e1f90c41f4a2ecbbd5963a1d1c486/tomli-2.3.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:f85209946d1fe94416debbb88d00eb92ce9cd5266775424ff81bc959e001acaf", size = 159088, upload-time = "2025-10-08T22:01:38.235Z" },
+    { url = "https://files.pythonhosted.org/packages/26/5a/4b546a0405b9cc0659b399f12b6adb750757baf04250b148d3c5059fc4eb/tomli-2.3.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a56212bdcce682e56b0aaf79e869ba5d15a6163f88d5451cbde388d48b13f530", size = 268193, upload-time = "2025-10-08T22:01:39.712Z" },
+    { url = "https://files.pythonhosted.org/packages/42/4f/2c12a72ae22cf7b59a7fe75b3465b7aba40ea9145d026ba41cb382075b0e/tomli-2.3.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c5f3ffd1e098dfc032d4d3af5c0ac64f6d286d98bc148698356847b80fa4de1b", size = 275488, upload-time = "2025-10-08T22:01:40.773Z" },
+    { url = "https://files.pythonhosted.org/packages/92/04/a038d65dbe160c3aa5a624e93ad98111090f6804027d474ba9c37c8ae186/tomli-2.3.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:5e01decd096b1530d97d5d85cb4dff4af2d8347bd35686654a004f8dea20fc67", size = 272669, upload-time = "2025-10-08T22:01:41.824Z" },
+    { url = "https://files.pythonhosted.org/packages/be/2f/8b7c60a9d1612a7cbc39ffcca4f21a73bf368a80fc25bccf8253e2563267/tomli-2.3.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:8a35dd0e643bb2610f156cca8db95d213a90015c11fee76c946aa62b7ae7e02f", size = 279709, upload-time = "2025-10-08T22:01:43.177Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/46/cc36c679f09f27ded940281c38607716c86cf8ba4a518d524e349c8b4874/tomli-2.3.0-cp314-cp314t-win32.whl", hash = "sha256:a1f7f282fe248311650081faafa5f4732bdbfef5d45fe3f2e702fbc6f2d496e0", size = 107563, upload-time = "2025-10-08T22:01:44.233Z" },
+    { url = "https://files.pythonhosted.org/packages/84/ff/426ca8683cf7b753614480484f6437f568fd2fda2edbdf57a2d3d8b27a0b/tomli-2.3.0-cp314-cp314t-win_amd64.whl", hash = "sha256:70a251f8d4ba2d9ac2542eecf008b3c8a9fc5c3f9f02c56a9d7952612be2fdba", size = 119756, upload-time = "2025-10-08T22:01:45.234Z" },
+    { url = "https://files.pythonhosted.org/packages/77/b8/0135fadc89e73be292b473cb820b4f5a08197779206b33191e801feeae40/tomli-2.3.0-py3-none-any.whl", hash = "sha256:e95b1af3c5b07d9e643909b5abbec77cd9f1217e6d0bca72b0234736b9fb1f1b", size = 14408, upload-time = "2025-10-08T22:01:46.04Z" },
+]
+
+[[package]]
+name = "typing-extensions"
+version = "4.13.2"
+source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+    "python_full_version < '3.9'",
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f6/37/23083fcd6e35492953e8d2aaaa68b860eb422b34627b13f2ce3eb6106061/typing_extensions-4.13.2.tar.gz", hash = "sha256:e6c81219bd689f51865d9e372991c540bda33a0379d5573cddb9a3a23f7caaef", size = 106967, upload-time = "2025-04-10T14:19:05.416Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8b/54/b1ae86c0973cc6f0210b53d508ca3641fb6d0c56823f288d108bc7ab3cc8/typing_extensions-4.13.2-py3-none-any.whl", hash = "sha256:a439e7c04b49fec3e5d3e2beaa21755cadbbdc391694e28ccdd36ca4a1408f8c", size = 45806, upload-time = "2025-04-10T14:19:03.967Z" },
+]
+
+[[package]]
+name = "typing-extensions"
+version = "4.15.0"
+source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+    "python_full_version >= '3.9'",
+]
+sdist = { url = "https://files.pythonhosted.org/packages/72/94/1a15dd82efb362ac84269196e94cf00f187f7ed21c242792a923cdb1c61f/typing_extensions-4.15.0.tar.gz", hash = "sha256:0cea48d173cc12fa28ecabc3b837ea3cf6f38c6d1136f85cbaaf598984861466", size = 109391, upload-time = "2025-08-25T13:49:26.313Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl", hash = "sha256:f0fa19c6845758ab08074a0cfa8b7aecb71c999ca73d62883bc25cc018c4e548", size = 44614, upload-time = "2025-08-25T13:49:24.86Z" },
+]
+
+[[package]]
+name = "zipp"
+version = "3.20.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/54/bf/5c0000c44ebc80123ecbdddba1f5dcd94a5ada602a9c225d84b5aaa55e86/zipp-3.20.2.tar.gz", hash = "sha256:bc9eb26f4506fda01b81bcde0ca78103b6e62f991b381fec825435c836edbc29", size = 24199, upload-time = "2024-09-13T13:44:16.101Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/62/8b/5ba542fa83c90e09eac972fc9baca7a88e7e7ca4b221a89251954019308b/zipp-3.20.2-py3-none-any.whl", hash = "sha256:a817ac80d6cf4b23bf7f2828b7cabf326f15a001bea8b1f9b49631780ba28350", size = 9200, upload-time = "2024-09-13T13:44:14.38Z" },
+]