{"id":13646252,"url":"https://github.com/sifive/Kami","last_synced_at":"2025-04-21T17:32:26.397Z","repository":{"id":77556537,"uuid":"120811630","full_name":"sifive/Kami","owner":"sifive","description":"Kami - a DSL for designing Hardware in Coq, and the associated semantics and theorems for proving its correctness. Kami is inspired by Bluespec. It is actually a complete rewrite of an older version from MIT","archived":false,"fork":false,"pushed_at":"2020-08-31T21:02:00.000Z","size":2168,"stargazers_count":201,"open_issues_count":12,"forks_count":12,"subscribers_count":72,"default_branch":"master","last_synced_at":"2025-04-03T19:51:09.326Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Coq","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/sifive.png","metadata":{"files":{"readme":"README.adoc","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}},"created_at":"2018-02-08T20:06:14.000Z","updated_at":"2025-03-16T22:09:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"f47f279f-2f9d-40b1-b9ce-22a95e10f527","html_url":"https://github.com/sifive/Kami","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sifive%2FKami","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sifive%2FKami/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sifive%2FKami/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sifive%2FKami/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sifive","download_url":"https://codeload.github.com/sifive/Kami/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250100707,"owners_count":21374988,"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":[],"created_at":"2024-08-02T01:02:51.478Z","updated_at":"2025-04-21T17:32:25.496Z","avatar_url":"https://github.com/sifive.png","language":"Coq","funding_links":[],"categories":["Coq"],"sub_categories":[],"readme":":toc:\n\n= Kami -- A Coq-based DSL for specifying and proving hardware designs\n\n== What is Kami?\nKami is an umbrella term used to denote the following:\n. A https://en.wikipedia.org/wiki/Coq[Coq]-based DSL for writing hardware designs\n. A compiler for translating said hardware designs into Verilog\n. A simulator for said hardware designs, by generating an executable\nin Haskell, using user-defined functions to drive inputs and examine\noutputs for the hardware design\n. A formal definition of the semantics of the DSL in Coq, including a\ndefinition of whether one design _implements_ another simpler design,\ni.e. whether an _implementation adheres to its specification_\n. A set of theorems or properties about said semantics, formally\nproven in Coq\n. A set of tactics for formally proving that an implementation adhere\nto its specification\n\nIn Kami, one can write generators, i.e. functions that\ngenerate hardware when its parameters are specified, and can prove that\nthe generators are correct with respect to their specification. Unlike\ntraditional model-checking based approaches, the ability to prove\ntheorems involving higher-order logic in Coq enables one to easily\nprove equivalence between a generator and its specification.\n\nThe semantics of Kami was inspired by\nhttp://wiki.bluespec.com/[Bluespec SystemVerilog]. The original\nversion of http://plv.csail.mit.edu/kami/papers/icfp17.pdf[Kami] was\ndeveloped in MIT.  Based on the experience of developing and using\nKami at MIT, it was rewritten at SiFive to make it practical to build\nprovably correct chips.\n\n== Semantics of Kami: an informal overview\nAny hardware block or _module_ is written as a set of registers\nrepresenting the state of the block, and a set of _rules_. The\nbehavior of the module is represented by a sequence of execution of\nrules. Rules execute by reading and writing the state _atomically_,\ni.e. when one rule is executing, no other rule executes. During its\nexecution, a rule can also interact with the external world by calling\nmethods, to which the rule supplies arguments (an output from the\nmodule), and takes back the result returned by the external world (an\ninput to the module). Once a rule finishes execution, another rule is\npicked non-deterministically and is executed, and so on.\n\nA module _A_ is said to implement a specification module _B_ if,\nduring every rule execution in _A_, if the rule calls any methods,\nthen these methods (along with their arguments and return values) are\nthe same as those called by some rule execution in _B_, and this\nproperty holds for every sequence of rule executions in _A_. Note that\nthe return values are functions of the external world; we assume that\nthe same value can be returned by the external world if the same\nmethod is called with the same argument in both _A_ and _B_.  The\nmethods along with their arguments and return values that are called\nin a rule's execution are called a label, and the sequence of labels\ncorresponding to the sequence of rule execution is called a trace.\nThe above definition of _A_ implementing _B_ can be rephrased as\nfollows: any trace that can be produced by _A_ can also be produced by\n_B_. We call this property `TraceInclusion`.\n\nWhile the above semantics cover most of the behavior of Kami modules,\nit is not complete. We will be discussing the last bit of the\nsemantics towards the end of this article.\n\n== Syntax of Kami\nThe syntax of Kami is designed to simply provide a way to represent a\nset of registers (with optional initial values), and a set of rules.\nThe rules are written as _actions_ which read or write registers, call\nmethods, deal with predicates (i.e. `if then else`), etc. The module\n`exampleModule` in link:Tutorial/SyntaxEx.v[SyntaxEx.v] shows an\nexample featuring all the syntactic components involved in writing a\nmodule, including writing every possible _expression_, _action_,\nregister initialization and rule. The comments in the file give an\ninformal specification of what each syntactic construct does.\n\nNotice that actions and let-expressions are essentially are\nhttps://en.wikipedia.org/wiki/Abstract_syntax_tree[ASTs] written in\nGallina. So, one can construct these actions or let-expressions\nseparately as Gallina terms without having to be inside a Kami\nmodule. This way, one can write generators that produce actions or\nlet-expressions that can be composed in multiple ways into a module.\nlink:Tutorial/GallinaActionEx.v[GallinaActionEx.v] shows how to write\nsuch Gallina terms. Notice the use of a strange parameter\n`ty: Kind -\u003e Type`. This is used to get parametric ASTs that allow us\nto use the same AST for synthesizing circuits as well as for\nproofs. Read a tiny example, link:Tutorial/PhoasEx.v[PhoasEx.v] and\nhttp://adam.chlipala.net/papers/PhoasICFP08/PhoasICFP08.pdf[Parametric\nHigher Order Abstract Syntax (PHOAS) paper] to understand what PHOAS\nmeans. While understanding PHOAS is useful, one need not understand\nthe concepts to build actions and let-expressions in Kami. Instead,\none can view supplying `ty: Kind -\u003e Types` as boiler plate code, and\nwrite types for expressions as `k @# ty`, let-expressions as `k ## ty`\nand actions as `ActionT ty k` (`k` represents the Kami type represented\nby these entities).\n\n== Proving implementations using Kami\nlink:Tutorial/TacticsEx.v[TacticsEx.v] showcases how some of the Coq tactics developed\nin the Kami framework can be used to simplify the proof of `TraceInclusion`\nbetween two modules. The documentation for this is work in progress.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsifive%2FKami","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsifive%2FKami","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsifive%2FKami/lists"}