{"id":30951159,"url":"https://github.com/revng/udb-to-qemu","last_synced_at":"2025-09-16T10:23:52.224Z","repository":{"id":313994139,"uuid":"1053521457","full_name":"revng/udb-to-qemu","owner":"revng","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-09T21:24:56.000Z","size":79,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-10T00:59:45.804Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/revng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-09T15:03:16.000Z","updated_at":"2025-09-09T21:24:59.000Z","dependencies_parsed_at":"2025-09-10T00:59:56.619Z","dependency_job_id":"c945822a-53c7-43a0-a47b-f995b298c29f","html_url":"https://github.com/revng/udb-to-qemu","commit_stats":null,"previous_names":["revng/udb-to-qemu"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/revng/udb-to-qemu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revng%2Fudb-to-qemu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revng%2Fudb-to-qemu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revng%2Fudb-to-qemu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revng%2Fudb-to-qemu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/revng","download_url":"https://codeload.github.com/revng/udb-to-qemu/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/revng%2Fudb-to-qemu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274584194,"owners_count":25311902,"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-09-11T02:00:13.660Z","response_time":74,"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":[],"created_at":"2025-09-11T05:43:47.313Z","updated_at":"2025-09-16T10:23:48.521Z","avatar_url":"https://github.com/revng.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# udb-to-qemu\n\nThis project takes RISC-V extensions defined in the [RISC-V Unified Database (UDB)](https://github.com/riscv-software-src/riscv-unified-db/) to fully functional QEMU frontends along with per-instruction edge case tests. The end goal is to allow for rapid prototyping and early bug-catching of RISC-V extensions currently in development.\n\n**NOTE**: Currently assumptions are made that Xqci/Xqccmp extensions are being used as input, these will be relaxed over time.\n\n## Usage\n\nStart with\n```\n$ git submodule update --init\n```\nto fetch submodules for `helper-to-tcg`, current version of QEMU `xqci/xqccmp` extensions, `riscv-unified-db`, along with tests (`embench`, `picolibc`).\n\nNext,\n```\n$ ./build-all-artifacts.sh ${path_to_clang++_for_klee} \\\n                           ${path_to_klee} \\\n                           ${path_to_llvm_config}\n```\nwill produce all build artifacts in the `build/` directory, note a separate version of `clang++` is specified for usage with KLEE which requires an older version of clang (tested with version 13 and 14). `llvm-config` is forwarded for building the LLVM-based `helper-to-tcg` tool which currently supports versions `10-14` inclusively.\n\nBuild artifacts are copied into the current QEMU version (`submodules/xqci`) via\n```\n$ ./install-qemu.sh\n```\nwhich overwrites all generated files.\n\nQEMU can be built via running\n```\n$ ./build-qemu.sh\n```\nwhich produces a build of `qemu-riscv32, qemu-system-riscv32` into `build/qemu`.\n\nAll auto-generated tests can be ran via\n```\n$ ./build-and-run-qemu-tests.sh ${path_to_toolchain_clang}\n```\nwhere a toolchain clang version is required for inline-assembly `C` tests.\n\n## Overview of Generated Artifacts\n\n### Instruction Definitions\n\nQEMU compatible instruction definitions in Tiny Code Generators (TCG) are produced by:\n    1. Generating `C++` code from instruction definitions in the UDB (`scripts/udb-to-cpp.py`), extra `C++` types and operators are defined in `cpp-templates/`;\n    2. Producing `LLVM IR` using `clang` (version 10-14), from the `C++` code;\n    3. Producing TCG using `helper-to-tcg` from the `LLVM IR`.\n\n### Instruction Decoding \n\nQEMU can already generate C code for decoding instructions from its own `decodetree` format. Mapping of UDB instruction encodings to QEMUs `decodetree` format is straight forward and carried out with the `scripts/udb-to-decodetree.py` script.\n\nIn QEMU decoding for instruction execution, and decoding for disassembly is slightly different and requires two separate functions to be provided per instruction. These extra functions are generated with `scripts/udb-to-trans.py`.\n\nLastly, some glue code needs to be generated to interface with the existing disassembler and fill out formatting information, this is generated by `scripts/udb-to-disas.py`.\n\n### Control and Status Registers (CSRs)\n\nMapping from UDB CSRs to QEMU CSRs is done by `scripts/udb-to-csr.py` and produces code for defining/accessing CSRs along with extension and privilege mode checks.\n\n### Instruction Tests\n\nThe main idea is to rely on the [KLEE](https://klee-se.org/) symbolic execution engine to collect tests for code coverage per-instruction. If dummy-branches are inserted to check for over-/underflow in overloaded operators (`cpp-templates/base-operators.h` with `KLEE_INPUT` and `OP_CHECK_OVERFLOW` defined), KLEE  will produce tests covering these branches as well. This is the main procedure used to create edge case tests for arithmetic, load, store, and branching operations.\n\nKLEE requires `LLVM IR` as input, which is generated from `scripts/udb-to-klee.py` to produce `C++` along with `clang++` for `LLVM IR`. Running KLEE on the `LLVM IR` produces tests for coverage, and running these tests produces a `YAML` file of expected inputs/outputs per instruction, which are later used to produce raw binary tests using `scripts/assemble.py` and `C` inline assembly tests using (`scripts/c.py`), the latter requires a toolchain with assembly support to actually use.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frevng%2Fudb-to-qemu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frevng%2Fudb-to-qemu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frevng%2Fudb-to-qemu/lists"}