{"id":28462744,"url":"https://github.com/galoisinc/grift","last_synced_at":"2025-08-28T19:23:31.119Z","repository":{"id":33836902,"uuid":"144071702","full_name":"GaloisInc/grift","owner":"GaloisInc","description":"Galois RISC-V ISA Formal Tools","archived":false,"fork":false,"pushed_at":"2025-04-01T15:38:37.000Z","size":7920,"stargazers_count":58,"open_issues_count":3,"forks_count":8,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-06-07T04:36:44.447Z","etag":null,"topics":["coverage","coverage-analysis","formal-methods","formal-specification","risc-v","simulation"],"latest_commit_sha":null,"homepage":null,"language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GaloisInc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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":"2018-08-08T21:56:13.000Z","updated_at":"2025-04-01T15:38:36.000Z","dependencies_parsed_at":"2024-01-18T19:59:01.830Z","dependency_job_id":null,"html_url":"https://github.com/GaloisInc/grift","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GaloisInc/grift","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaloisInc%2Fgrift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaloisInc%2Fgrift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaloisInc%2Fgrift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaloisInc%2Fgrift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GaloisInc","download_url":"https://codeload.github.com/GaloisInc/grift/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaloisInc%2Fgrift/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262897503,"owners_count":23381434,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coverage","coverage-analysis","formal-methods","formal-specification","risc-v","simulation"],"created_at":"2025-06-07T04:36:44.292Z","updated_at":"2025-07-01T04:32:44.430Z","avatar_url":"https://github.com/GaloisInc.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"GRIFT - Galois RISC-V ISA Formal Tools\n===\n\ncopyright (c) Galois Inc. 2018\n\n*Galois RISC-V ISA Formal Tools* (hereafter, *GRIFT*) is part of the BESSPIN\nsoftware suite, developed by Galois, Inc. It contains a concrete representation\nof the semantics of the RISC-V instruction set, along with an elegant\nencoding/decoding mechanism, and simulation and analysis front-ends. It is\nintended for broad use in the RISC-V community - simulation, binary analysis,\nand software \u0026 hardware verification/validation are all current and/or potential\nfuture uses for *GRIFT*, and we have designed it specifically with these broad\napplication domains in mind.\n\n*GRIFT* differs from other Haskell-based RISC-V formalizations in its coding\nstyle (using highly dependently-typed GHC Haskell) and some of its foundational\ndesign decisions. Its primary use is as a library, providing mechanisms for the\nencoding/decoding of instructions, as well as running RISC-V programs in\nsimulation. However, the semantics of the instructions themselves are\nrepresented, not as Haskell functions on a RISC-V machine state (registers, PC,\nmemory, etc.), but as symbolic expressions in a bitvector expression\nlanguage. This extra layer of representation, while sub-optimal for fast\nsimulation, facilitates the library's use as a general-purpose encoding of the\nsemantics, and makes *GRIFT* a general-purpose, \"golden reference\" model that\ncan be easily translated into the syntax of other tools by providing minimal\npretty printers, written in Haskell, for the underlying bitvector expression\nlanguage. Having explicit semantic data for each instruction also facilitates\nthe library's incorporation with other Haskell-based tooling, such as coverage\nanalysis (where a notion of coverage is encoded in the same bitvector language\nas the semantics), binary analysis, and verification, both within and without\nthe Haskell programming environment.\n\nBuild instructions\n===\n\n## 1. Setup\nWe assume you have [ghc](https://www.haskell.org/ghc/download.html) version\n8.4.4 or greater, and [cabal](https://www.haskell.org/cabal/download.html)\nversion 2.4.1.0 or greater. Run a `cabal update` before you begin.\n\n## 2. Clone dependencies\n\nFirst, clone all the dependencies recursively:\n```shell\n$ git submodule update --init --recursive\n```\n\n## 3. Install softfloat\nGRIFT depends on softfloat-hs, which in turn depends on the softfloat\nlibrary. To install it on Linux or OSX, run:\n```shell\n$ cd deps/softfloat-hs\n$ make\n$ sudo make install\n```\n\nThe Makefile in `deps/softfloat-hs` should install the softfloat library and\nheader files to the appropriate locations on both OSX and Linux.\n\n## 4. Build GRIFT\nFinally, build GRIFT and all associated executables using cabal v2-build:\n```shell\n$ cabal v2-build all\n```\n\n## 5. Install GRIFT\nIdeally, the following command should install the `grift-sim` and\n`grift-doc` tools to ~/.cabal/bin:\n```shell\n$ cabal v2-install all --overwrite-policy=always\n```\n\nUnfortunately, the `v2-install` feature is evolving, and you may run into\nissues. If this does not work, you can find the executable generated by `cabal\nv2-build` by `grep`ping in the `dist-newstyle` directory. Once you find it, you\nshould copy it somewhere on your PATH.\n\nRunning `grift-sim`\n===\n\n## Simulating a single ELF file\n\n`grift-sim` is the GRIFT simulation and coverage analysis tool. Try running it\non the executable at `test/fib`:\n\n```shell\ngrift-sim --halt-pc=0 --reg-dump test/fib/fib\n```\n\nThis will run the executable and dump the contents of some registers. You should\nbe able to do this with any executable. If you compile your executable for a\n32-bit RISC-V program, you will need to use `-a RV32GC` to switch to 32-bit\nmode.\n\nThe `--halt-pc=0` option tells `grift-sim` to stop simulating as soon as the\nprogram counter is equal to 0. You can change this value for your particular\napplication. You can also limit the number of instructions executed in\nsimulation by using the `--steps` option.\n\nIf you want to view a region of memory after simulation instead of the register\nfiles, use the `--mem-dump-begin` and `--mem-dump-end` options:\n\n```shell\ngrift-sim --halt-pc=0 --mem-dump-begin=0x11c90 --mem-dump-end=0x11c93 test/fib/fib\n```\n\nThis will dump the contents of the memory between those memory locations; each\nline will be 8 digits (four bytes).\n\nThe --halt-pc and --mem-dump-* options also take symbols, rather than raw\naddresses, as arguments.\n\n## Analyzing instruction coverage\n\n`grift-sim` can be used to inspect coverage of the RISC-V instruction set.\n\n```shell\ngrift-sim --halt-pc=0 --inst-coverage=add test/fib/fib\n```\n\nThis will print out the semantic branching structure of the ADD instruction's\nsemantics, and will highlight the various branch conditions with colors\nindicating the coverage of that instruction throughout execution. We can also\ntrack coverage of the entire instruction set by using `--inst-coverage=all`,\nwhich logs coverage of every instruction and prints out a report after the run.\n\n`grift-sim` can also be used to analyze coverage of an entire test suite. If\n`test-suite` is a directory containing only ELF files that we want to simulate,\nwe can try\n\n```shell\ngrift-sim --halt-pc=0 --inst-coverage=all test-suite/*\n```\n\nwhich will track coverage of all instructions after running all the tests back\nto back. This is how we analyze coverage for the Compliance Working Group's test\nsuite. Just as for a single ELF file, we can dive into coverage of a particular\ninstruction by setting `--inst-coverage=` for whichever instruction we are\ninterested in.\n\n## Other\n\nType `grift-sim --help` for a full list of invocation\ninstructions.\n\n`grift-doc`\n===\n\nGRIFT also comes with the `grift-doc` executable, which is used to inspect the\nencoding and semantics of individual instructions.\n\nRequirements\n===\n\nThe following are a list of mandatory and secondary requirements for *GRIFT*.\n\n# Mandatory Requirements\n\n## General\n\n- Must represent semantics of all RISC-V behavior (instructions and exceptional\n  behavior) in a manipulatable and inspectable embedded bitvector expression\n  language.\n- Must have a type-level representation of the major aspects of the RISC-V\n  feature model: register width and implemented extensions. To run in\n  simulation, it should be enough to specify this information at the type\n  level, and have the appropriate instance of RISC-V automatically.\n- Coverage analysis and test generation tooling for RISC-V Compliance Task\n  Group.\n\n## RISC-V support\n\n- Must support RV32G/RV64G.\n- Must support all privilege modes (M, S, U), modeling exceptional behavior\n  accurately and completely.\n- Must capture all other \"customizable\" aspects of the ISA (e.g. misaligned\n  accesses in hardware).\n\n## Simulation\n\n- Must be able to run all code compiled by the RISC-V GCC toolchain (including,\n  but not limited to, booting the Linux kernel). However, performance in\n  simulation is explicitly *not* a concern.\n- Must pass all relevant tests from riscv-tests and riscv-compliance test\n  suites.\n- Must integrate with SVF bisimulation tooling for hardware validation.\n\n## Documentation\n\n- Core Haskell code must be cleanly Haddock-documented.\n- Instruction semantics should pretty-print to pseudocode in a readable form, in\n  the style of the RISC-V Reader (Appendix A) pseudocode.\n\n# Secondary Requirements\n\n- Straightforward integration with other languages, tools, and frameworks (Coq,\n  Verilog, ...)\n- Cabal-driven test suite incorporating riscv-tests and riscv-compliance test\n  suites (among other tests)\n\nCurrent Status\n===\n\nGRIFT is not being actively maintained by Galois at present; it may be\nresurrected in the future, however.\n\nWe currently support RV{32|64}IMAFDC, with M-mode privileged instructions. Exceptions\nare modeled incompletely; the bare minimum to run user-level code with traps is\nsupported. We are passing all the following tests in simulation:\n\n- rv32ui\n- rv64ui\n- rv32um\n- rv64um\n- rv32ua (except lrsc)\n- rv64ua (except lrsc)\n- rv32uf\n- rv64uf\n- rv32ud\n- rv64ud\n- rv32uc\n- rv64uc\n\nWe also now provide a command-line option to select a RISC-V architecture\nvariant. Not every combination is possible -- legal ones begin with \"RV32\" or \"RV64\"\nand end in \"I\", \"IM\", \"IMA\", \"IMAF\", \"G\", or \"GC\".\n\nWe also support the --inst-coverage=OPCODE command-line option for testing coverage\nof a particular instruction, based on that instruction's semantic if/then/else\nbranching structure. This type of coverage analysis is flexible enough to accomodate\nmost kinds of coverage, not necessarily based purely on the semantics of the\ninstruction in question. However, this would require a bit of hand-coding because we\ndo not support an option in grift-sim to specify exactly what kind of coverage to\nkeep track of. This is an area of active development, and we are open to suggestions\non this.\n\nKnown issues\n===\nBuilding softfloat on Darwin currently has some issues -- for whatever reason, some\nof the conversion functions to not work correctly in some of the corner\ncases. Therefore, some of GRIFT's behavior may not be entirely correct unless it is\nrun in Linux. We are investigating this issue.\n\nOther information\n===\n\n* contact: benselfridge@galois.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaloisinc%2Fgrift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgaloisinc%2Fgrift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaloisinc%2Fgrift/lists"}