{"id":17694161,"url":"https://github.com/can-lehmann/pathbeaver","last_synced_at":"2025-07-30T21:12:55.155Z","repository":{"id":214909269,"uuid":"733994792","full_name":"can-lehmann/pathbeaver","owner":"can-lehmann","description":"Symbolic execution of LLVM IR","archived":false,"fork":false,"pushed_at":"2024-01-03T03:22:06.000Z","size":60,"stargazers_count":13,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-13T03:47:43.685Z","etag":null,"topics":["equivalence-checker","formal-verification","llvm","symbolic-execution"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/can-lehmann.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-20T15:58:47.000Z","updated_at":"2024-01-03T03:40:27.000Z","dependencies_parsed_at":"2024-01-03T04:36:49.014Z","dependency_job_id":"12f3d0a0-f45b-4cd9-91e2-42ba8d407235","html_url":"https://github.com/can-lehmann/pathbeaver","commit_stats":null,"previous_names":["can-lehmann/pathbeaver"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/can-lehmann/pathbeaver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/can-lehmann%2Fpathbeaver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/can-lehmann%2Fpathbeaver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/can-lehmann%2Fpathbeaver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/can-lehmann%2Fpathbeaver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/can-lehmann","download_url":"https://codeload.github.com/can-lehmann/pathbeaver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/can-lehmann%2Fpathbeaver/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267942823,"owners_count":24169858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["equivalence-checker","formal-verification","llvm","symbolic-execution"],"created_at":"2024-10-24T13:48:01.158Z","updated_at":"2025-07-30T21:12:55.098Z","avatar_url":"https://github.com/can-lehmann.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pathbeaver\n\nPathbeaver is a symbolic execution engine for LLVM IR.\nIts main application is hardware/software equivalence checking.\n\nTake a look at these two implementations of the absolute value function.\nWe can use pathbeaver to prove that they are equivalent.\n\n```c\nint64_t abs_1(int64_t x) {\n  if (x \u003c 0) {\n    return -x;\n  } else {\n    return x;\n  }\n}\n\nint64_t abs_2(int64_t x) {\n  return (x ^ (x \u003e\u003e 63)) + ((x \u003e\u003e 63) \u0026 1);\n}\n```\n\nWe use pathbeaver to execute both functions on a symbolic input.\n\n```cpp\nhdl::Value* x = module.input(\"x\", 64);\n\npathbeaver::Trace trace(module, globals);\npathbeaver::Value ret_a = trace.trace_simple(llvm_module-\u003egetFunction(\"abs_1\"), {x});\npathbeaver::Value ret_b = trace.trace_simple(llvm_module-\u003egetFunction(\"abs_2\"), {x});\n```\n\nThen we prove the equivalence of the resulting traces using Z3:\n\n```cpp\nz3::context context;\nz3::solver solver(context);\nhdl::proof::z3::Builder builder(context);\n\nbuilder.free(x);\nbuilder.require(\n  solver,\n  module.op(hdl::Op::Kind::Eq, {\n    ret_a.primitive(), ret_b.primitive()\n  }),\n  hdl::BitString::from_bool(false)\n);\n\nstd::cout \u003c\u003c solver.check() \u003c\u003c std::endl;\n```\n\nRunning this outputs\n\n```bash\n$ make\nclang++ -g -I/usr/include/z3 -lz3 `llvm-config-16 --cflags --libs` main.cpp -o main\nclang -Xclang -disable-O0-optnone -c -emit-llvm -o abs.bc abs.c\n./main abs.bc\nunsat\n```\n\n**Note:** Pathbeaver is currently a hobby project and should not be used for important applications.\nIf you are interested in collaborating on projects involving pathbeaver, feel free to get in contact by opening an issue.\n\n## Installation\n\nPathbeaver requires LLVM 16 and the Z3 theorem prover.\n\n```bash\n$ git clone https://github.com/can-lehmann/pathbeaver.git\n$ cd pathbeaver\n$ git submodule update --init\n$ make test\n```\n\n## Documentation\n\nYou can find examples in the [examples](examples/) folder.\n\n## References\n\nPathbeaver is inspired by and based on techniques developed in other symbolic execution projects such as KLEE and SAW.\nIt uses LLVM and the Z3 theorem prover.\n\n## License\n\nCopyright 2023 Can Joshua Lehmann\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcan-lehmann%2Fpathbeaver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcan-lehmann%2Fpathbeaver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcan-lehmann%2Fpathbeaver/lists"}