Skip to content
panda-rePublic

About

No description, website, or topics provided.

Resources

Stars

5 stars

Watchers

5 watching

Forks

Repository files navigation

panda-ng (panda-next)

PANDA on QEMU 11.1: the engine (upstream QEMU with PANDA's patch series and sources, in engine/, built with --enable-panda), the headers libpanda-ng generates from it, panda-ng's plugins, and pandare2, the Python interface. Everything is built by this repository's nix flake, from this repository. There are three ways to use it:

you want use
pip install into your own Python the wheel: pandare2-<v>-py3-none-manylinux_2_38_<arch>.whl
to build on it with nix the flake: packages, apps, overlays.default, lib
plain QEMU qemu-system-<arch>, from the flake (nix run) or the wheel (console scripts)

Supported hosts: x86_64-linux and aarch64-linux. Targets: x86_64, i386, arm, aarch64, mips, mipsel, mips64, mips64el, ppc, ppc64, loongarch64, riscv32, riscv64.

Documentation is in docs/ (nix build .#docs builds the site): what works and how well tested it is (docs/features.md), the Python API, every callback and whether it fires, and the engine patches. The generated pages are checked by nix flake check; after changing docs/features.toml, an engine header or a test's callback lists, run nix run .#regen-docs.

The wheel

python3 -m venv venv
venv/bin/pip install pandare2-*-manylinux_2_38_$(uname -m).whl
venv/bin/python -c 'from pandare2 import Panda; Panda(arch="x86_64", mem="256M")'
venv/bin/qemu-system-riscv64 -version

The wheel needs glibc 2.38 or newer (Debian 13, Ubuntu 24.04, Fedora 39, RHEL 10 and later) and nothing else from the host: the engine (libpanda-<arch>-softmmu.so), the plugins, QEMU's firmware, the qemu-system-<arch> launcher, and every library they use apart from glibc (glib, pixman, libslirp, libstdc++, ...) are inside it. It works with any Python 3 the host has (pandare2's bindings are cffi ABI mode, so the wheel is py3-none). It is about 120 MB.

Build it with nix build .#wheel (the wheel is in result/). How it's made:

  1. enginePortable: the engine built with nix/glibc-compat/termios-compat.c linked in. nix's glibc is 2.42, whose cfsetispeed/cfsetospeed have new symbol versions (speed_t became the baud rate itself). Those were the only symbols newer than GLIBC_2.38 anywhere in the engine, plugins or their libraries; the shim translates the rate to the old code and calls the original version, which every glibc has. The engine is otherwise the same as .#engine.
  2. pip wheel builds the pure-Python pandare2 (with the cffi bindings generated from that engine's headers).
  3. tools/wheel/repair.py adds the engine, plugins, firmware and launcher under pandare2/data/, and does what auditwheel repair does: it copies each needed library except glibc's into pandare2.libs/ under a hashed name, rewrites DT_NEEDED and RUNPATH ($ORIGIN), gives the launcher the standard ELF interpreter, fails if anything still points into /nix/store or needs a glibc newer than 2.38, and tags the wheel manylinux_2_<highest GLIBC_2.N needed>_<arch>. (auditwheel itself won't bundle libstdc++, and nix's is newer than the hosts'.) Libraries the wheel ships itself (engine, plugins) are never copied again, every RUNPATH is $ORIGIN:$ORIGIN/<to pandare2.libs>, and no soname is bundled twice.
  4. Licenses: the wheel contains GPL-2.0-only QEMU and LGPL/BSD/MIT/... libraries, not just the MIT Python package. pandare2-*.dist-info/licenses/ holds each component's license files (taken from its upstream source) and SOURCES.txt, which says where each one's source is (the panda-ng commit and engine/'s patch series for the engine, the panda-ng commit, each library's upstream tarball). METADATA has the combined License-Expression. The list of libraries and their licenses is wheelThirdParty in flake.nix; repair.py fails if it bundles a library from a package not on it.

pandare2 looks for its engine, plugins and firmware in pandare2/data/, then in the flake's (which builds them into pandare2), so the same source works from the wheel and from nix. PANDA_LIB, PANDA_PLUGIN_DIR and Panda(libpanda_path=, plugin_path=, biospath=) point it elsewhere, e.g. at a build tree.

Older hosts (glibc < 2.38: Ubuntu 22.04, Debian 12) would need the engine built in a manylinux container instead; pip refuses the wheel there rather than failing at import.

The flake

Packages (nix build .#<name>), for x86_64-linux and aarch64-linux:

package what
engine QEMU + PANDA: lib/libpanda-<arch>-softmmu.so, include/panda-ng/, share/qemu/, QEMU's tools
engine-x86_64 one target, for iterating on the build
engine-src the patched QEMU tree the engine builds from (tarball + engine/patches + engine/src)
plugins (default) lib/panda/plugins/libpanda-<plugin>_<arch>-softmmu.so
pandare2 the Python package, wired to this engine and these plugins
python nix's Python with pandare2
qemu bin/qemu-system-<arch> for every target (+ qemu-img, qemu-io, qemu-nbd)
qemu-system-<arch> one of those
plugin-sdk headers for building a plugin outside this tree
dist engine + plugins + python under one prefix (panda-python, panda-system-<arch>)
deb dist's closure as a .deb (bundles nix's Python; any Debian/Ubuntu)
wheel the pip wheel

Apps: nix run .#qemu-system-<arch> -- <qemu args>, nix run .#python -- script.py.

Using it from another flake

examples/consumer is a complete one: it builds an out-of-tree C plugin against the engine, runs a pandare2 script that loads it, and re-exports qemu.

{
  inputs.panda-ng.url = "github:panda-re/panda-ng/workspace/panda-next";
  inputs.nixpkgs.follows = "panda-ng/nixpkgs";   # share panda-ng's builds

  outputs = { nixpkgs, panda-ng, ... }:
    let
      system = "x86_64-linux";
      pkgs = import nixpkgs { inherit system; overlays = [ panda-ng.overlays.default ]; };
      pn = panda-ng.lib.${system};
    in {
      packages.${system} = {
        # overlay: pkgs.pandaNext.<package>, and pandare2 in every Python package set
        python = pkgs.python3.withPackages (ps: [ ps.pandare2 ]);
        qemu = pkgs.pandaNext.qemu;
        # lib: build a plugin against the engine's headers
        myplugin = pn.buildPandaPlugin { pname = "myplugin"; src = ./plugin; };
      };
    };
}
  • overlays.default adds pandaNext (everything in the table above, plus the helpers below) built with the consumer's nixpkgs, and pandare2 to every Python package set through pythonPackagesExtensions.
  • lib.<system>: this flake's engine, plugins, pluginDir, pluginSdk, qemu, pandare2, python, and:
    • buildPandaPlugin { pname, src, targets ? [ "x86_64" "aarch64" "riscv64" ], buildInputs, extraCFlags }: compiles every *.c in src into lib/panda/plugins/libpanda-<pname>_<arch>-softmmu.so. It builds against engine's generated headers; such a plugin also works with the wheel's engine (enginePortable) only while both come from the same engine source revision.
    • pluginDirWith [ drv ... ]: a plugin directory with panda-ng's plugins and yours, for PANDA_PLUGIN_DIR or Panda(plugin_path=...).
    • mkEngine { targets, portable }: an engine for other targets.
  • lib.mkPandaNext pkgs: the whole set for any nixpkgs (what the overlay calls).

Checks: nix flake check applies the engine's series (engine-src) and runs -version and -machine help on every qemu-system-<arch>. nix develop .#engine is the engine's toolchain.

For working on the engine, the plugins or pandare2, tools/dev/dev.sh build --targets x86_64 keeps an incremental build of all three in .dev/, and .dev/bin/python3 runs pandare2 from python/core on it (docs/guides/development.md).

The engine

engine/README.md: the layout (base.json, patches/<version>/, src/), working on the series (import, export, verify), the CI gates, rebasing onto a new QEMU release, and what came from rehosting/qemu_builder, where the engine lived until October 2026. Engine work (the series, the overlay in engine/src/, its tests) happens here now; nothing is taken from qemu_builder any more.

qemu-system-<arch>

nix run .#qemu-system-aarch64 -- -M virt -cpu max -bios edk2-aarch64-code.fd -m 1G \
    -display none -serial stdio -drive file=disk.qcow2,if=virtio
venv/bin/qemu-system-x86_64 -version        # from the wheel

The engine is built as a library, libpanda-<arch>-softmmu.so (the object pandare2 loads), and qemu-system-<arch> is launcher/panda-qemu.c: a few kB that dlopens that library (RTLD_GLOBAL) and calls its main(). It picks the arch from its name (qemu-system-<arch>, panda-system-<arch>, or panda-qemu <arch> ...), finds the library in ../lib (or $PANDA_QEMU_LIBDIR), and QEMU finds its firmware in ../share/qemu relative to the launcher. Why a launcher rather than the engine's own bin/qemu-system-* executables or linking those with --export-dynamic:

  • it runs exactly the code pandare2 runs, and everything the library exports (the PANDA API) is visible to plugins QEMU loads; the engine's executables export only qemu_plugin_* (80 symbols, no panda_*), so a PANDA plugin can't load in them;
  • --export-dynamic would fix the exports, but each executable is still a second ~25 MB copy of its target (308 MB for 13), which the wheel and the .deb would have to carry next to the libraries; the launcher costs nothing.

The engine still installs its own bin/qemu-system-* (the engine and dist outputs keep them for now).

License

panda-ng's own code is under the MIT license (LICENSE). Code that comes from elsewhere keeps its license. REUSE.toml gives the license of every file, and the texts are in LICENSES/. reuse lint checks them.

  • MIT: panda-ng's own code (pandare2's new modules, tools, tests, build files, the launcher).
  • GPL-2.0-or-later: the engine (engine/: patches to QEMU and the overlay linked into it), and the pandare2 modules and headers taken from classic PANDA (panda-re/panda).
  • GPL-2.0-only: classic PANDA's plugins and other files whose header says "GNU GPL, version 2"; the bindings generated from the engine's headers (rust/panda-bindings/src/autogen/).
  • Each patch in engine/patches/<version>/ has a SPDX-License-Identifier: trailer (the licenses of the QEMU files it changes) and an Origin: trailer (upstream QEMU, classic PANDA, penguin, ...); ORIGINS.md there lists them.
  • Vendored: nlohmann/json (MIT), pycparser's fake libc headers (BSD-3-Clause), Volatility's syscall tables (GPL-2.0-or-later), Linux kernel excerpts (GPL-2.0-only).

The engine as built is QEMU and so GPL-2.0-only as a whole (QEMU's LICENSE). The wheel bundles the engine, the plugins and third-party libraries; its METADATA has the combined License-Expression, and pandare2-*.dist-info/licenses/ has every component's license files.

About

No description, website, or topics provided.

Resources

Stars

5 stars

Watchers

5 watching

Forks

Releases

Packages

Contributors

Languages