{"id":14966280,"url":"https://github.com/sifive/riscvspecformal","last_synced_at":"2025-10-30T00:31:21.616Z","repository":{"id":77556588,"uuid":"169319054","full_name":"sifive/RiscvSpecFormal","owner":"sifive","description":"The RiscvSpecKami package provides SiFive's RISC-V processor model. Built using Coq, this processor model can be used for simulation, model checking, and semantics analysis. The RISC-V processor model can be output as Verilog and simulated/synthesized using standard Verilog tools.","archived":false,"fork":false,"pushed_at":"2020-04-24T20:56:01.000Z","size":28100,"stargazers_count":76,"open_issues_count":0,"forks_count":7,"subscribers_count":63,"default_branch":"master","last_synced_at":"2025-02-02T05:51:09.998Z","etag":null,"topics":["coq","formal-verification","hardware","hardware-designs","riscv","riscv-simulator"],"latest_commit_sha":null,"homepage":"","language":"Haskell","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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-05T21:52:59.000Z","updated_at":"2025-01-29T14:18:32.000Z","dependencies_parsed_at":"2023-09-06T02:15:21.998Z","dependency_job_id":null,"html_url":"https://github.com/sifive/RiscvSpecFormal","commit_stats":{"total_commits":906,"total_committers":13,"mean_commits":69.6923076923077,"dds":0.3752759381898455,"last_synced_commit":"a57c67fe2640641c379720678f4d1d445edd1ae3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sifive%2FRiscvSpecFormal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sifive%2FRiscvSpecFormal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sifive%2FRiscvSpecFormal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sifive%2FRiscvSpecFormal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sifive","download_url":"https://codeload.github.com/sifive/RiscvSpecFormal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238912942,"owners_count":19551454,"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":["coq","formal-verification","hardware","hardware-designs","riscv","riscv-simulator"],"created_at":"2024-09-24T13:36:09.072Z","updated_at":"2025-10-30T00:31:20.620Z","avatar_url":"https://github.com/sifive.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"// image:https://travis-ci.org/sifive/RiscvSpecFormal.svg?branch=master[\"Build Status\", link=\"https://travis-ci.org/sifive/RiscvSpecFormal\"]\n\n:sectnums:\n:toc:\n\n= Formal Specification of RISC-V ISA in Kami\n\n\nThis project gives the formal specification of RISC-V ISA in\nhttps://github.com/sifive/Kami[Kami]. In particular, it gives the\nsemantics for RV32GC and RV64GC ISAs with User-mode, Supervisor-mode and\nMachine-mode instructions and the Zam extension (unaligned atomics).\n\nInstallation instructions are available in link:INSTALL.adoc[].\n\n== Organization\nThe semantics are organized into two parts, the\nhttps://github.com/sifive/ProcKami/tree/master/FuncUnits[ProcKami/FuncUnits]\ndirectory, and the top-level\nhttps://github.com/sifive/ProcKami[ProcKami] directory.\n\n=== FuncUnits directory\nThis is a directory that contains a list of instructions that defines\nthe RISC-V ISA, along with the semantics of these instructions,\nwritten as Kami expressions, that define how the instruction reads and\nupdates the state of a processor such as the register files, the\nfloating point register files, the PC, etc.\n\nThe directory is organized as the different functional units that execute\na set of instructions, each, of the RISC-V ISA. Related functional units\nare grouped together into directories (e.g., the different functional units\ncomprising the ALU functional units, such as the\nhttps://github.com/sifive/ProcKami/tree/master/FuncUnits/Alu/Add.v[Add],\nhttps://github.com/sifive/ProcKami/tree/master/FuncUnits/Alu/Add.v[Logical],\nhttps://github.com/sifive/ProcKami/tree/master/FuncUnits/Alu/Add.v[Branch],\nhttps://github.com/sifive/ProcKami/tree/master/FuncUnits/Alu/Add.v[DivRem],\netc. are grouped into the\nhttps://github.com/sifive/ProcKami/tree/master/FuncUnits/Alu[ProcKami/FuncUnits/Alu]\ndirectory).\n\nEach functional unit is is represented by a record which contains the\nfollowing fields:\n\nfuName:: The name of the functional unit (for documentation purposes only)\nfuFunc:: The function represented by the functional unit as a Kami\n  expression (which takes some inputs, in the form of a Kami struct\n  and produces some outputs, again in the form of a Kami struct)`\nfuInsts:: The list of instructions that are supported by this functional unit.\nThe fuInsts itself is a list of records where each record contains the\nfollowing fields:\ninstName::: The name of the instruction (for documentation purposes only)\nextensions::: The list of extensions that the instruction is necessary to be included in\nuniqId::: The unique identification information for the instruction as\n  defined by the RISC-V ISA. It contains a list of ranges (between 0\n  and 31) and the bit patterns in those ranges\ninputXform::: The transformation of the generic *_ExecContextPkt_* and *_ContextCfgPkt_*\ninto the inputs for the functional unit that executes this instruction.\n\n* *ExecContextPkt* represents the register state which the current\n   instruction that is being executed requires to execute. It contains\n   the following fields:\npc:::: The PC of the instruction packet\nreg1:::: The value in the register file for the first register\n    referenced by the instruction packet, in either the integer\n    register file or the floating point register file, depending on\n    the instruction\nreg2:::: The value in the register file for the second register\n    referenced by the instruction packet, again, in either the integer\n    register file or the floating point register file, depending on the\n    instruction\nreg3:::: The value in the register file for the third register\n    referenced by the instruction packet. This is needed only for the\n    FMADD instruction and its variants, and therefore necessarily from\n    the floating point register file\nfflags:::: The current status of the floating point flags, in order to set the new flags\nfrm:::: The floating point rounding mode\ninst:::: The uncompressed 32-bit instruction represented by the current packet\ncompressed?:::: Whether the instruction represented by the current\n    packet was compressed or not\n\n* *ContextCfgPkt* represents more of the register state which the\n   current instruction requires to execute. The difference from the\n   ExecContextPkt is that this represents the state which changes less\n   frequently as opposed to the state represented by the\n   ExecContextPkt, which changes more or less after exery\n   instruction. It contains the following fields:\n\nxlen:::: Specifies whether we are running the 32-bit ISA or the 64-bit ISA\nmode:::: Specifies whether we are in user mode, supervisor mode,\n    hypervisor mode or machine mode\nextensions:::: Specifies the extensions that the machine should be\n    supporting when executing the current instruction\ninstMisalignedException?:::: Specifies whether the instruction should\n    throw an exception when fetching an instruction not aligned to\n    32-bit boundaries\nmemMisalignedException?:::: Specifies whether the instruction should\n    throw an exception when performing a load, store, AMO or LR/SC on\n    an unaligned address\naccessException?:::: Specifies whether the instruction should throw\n    an access fault instead of misaligned fault (memory accesses\n    resulting in misaligned faults are usually still completed by the\n    trap handler by splitting the access into multiple aligned\n    accesses; access faults result in system error)\n    \noutputXform::: Specifies how to transform the output of a functional unit\ninto a processor-state update packet *ExecUpdPkt*, which contains the\nfollowing fields:\n\nval1:::: The value for the first destination register, along with\nwhether it is an updated value of an integer register or a floating\npoint register, the PC, the floating point flags register, a memory\naddress, a memory data (for stores and AMOs) or a CSR register.\n\nval2:::: Same as _*val1*_. This is needed when we update multiple\nlocations, for instance the PC and an integer register in case of the\nJALR instruction.\n\nmemBitMask:::: The memory mask for Store, AMO and SC operations\n\nmem:::: The value written to memory for Store, AMO and SC operations\n\ntaken?:::: In case of a branch or jump instruction, tells whether the\nbranch or jump is taken or not\n\naq:::: In case of AMO or LR/SC operation, tells whether it has the\nhttps://en.wikipedia.org/wiki/Release_consistency[acquire] semantics\n\nrl:::: In case of AMO or LR/SC operation, tells whether it has the\nhttps://en.wikipedia.org/wiki/Release_consistency[release] semantics\n\noptMemXform::: In case of memory-related instructions, specifies\nhow the data from the memory is transformed before storing into\nthe register file (for instance, in the case of a load byte, load\nhalf word, etc), and how the register value gets transformed before storing\ninto the memory (in the case of a store byte, store half word, etc). This\nfunction takes a *_MemoryInput_* packet that specifies what comes out\nof the register file and what comes out of the memory and transforms\nit into a *_MemoryOutput_* packet that specifies what goes into the\nregister file and what goes into the memory.\n\n*_MemoryInput_*:::: It has the following fields:\n\naq::::: In case of AMO or LR/SC operation, tells whether it has the\nhttps://en.wikipedia.org/wiki/Release_consistency[acquire] semantics\n\nrl::::: In case of AMO or LR/SC operation, tells whether it has the\nhttps://en.wikipedia.org/wiki/Release_consistency[release] semantics\n\nreservation::::: In case of LR/SC, specifies whether the reservation bit is\nset for each byte corresponding to the memory operation\n\nmem::::: The value written into the memory in case of a store, AMO or SC\n\nreg_data::::: The value written into the register file in case of a load, AMO or LR\n\n*_MemoryOutput_*:::: It has the following fields:\n\naq::::: In case of AMO or LR/SC operation, tells whether it has the\nhttps://en.wikipedia.org/wiki/Release_consistency[acquire] semantics\n\nrl::::: In case of AMO or LR/SC operation, tells whether it has the\nhttps://en.wikipedia.org/wiki/Release_consistency[release] semantics\n\nisWr::::: Tells whether the memory operation involves writing the memory (i.e. Store,\nAMO or SC)\n\nmask::::: Tells which bytes  will be written in case of Store, AMO or SC\n\ndata::::: Tells the written value in case of Store, AMO or SC\n\nisLrSc::::: Tells whether the operation is LR or SC\n\nreservation::::: Tells which bytes will be reserved in case of LR and which bytes' reservations\nhave to be checked in case of SC\n\ntag::::: Tells whether the value from a load is written into the integer register file or floating\npoint register file\n\nreg_data::::: Tells the value read in case of Load, AMO or LR\n\ninstHints::: Specifies various information about the instruction,\nsuch as whether it has a source 1 integer register, source 2 integer\nregister, destination integer register, source 1 floating point\nregister, source 2 floating point register, source 3 floating point\nregister, destination floating point register, whether it is a branch,\na jump to a register, a jump to an immediate value, a system call, a\nCSR-related instruction, a store or AMO instruction, etc.\n\nOne reason for such an organization, where each functional unit\nhandles a set of instructions is for clarity. The other, more\nimportant reason is as follows. We want to be able to automatically\nanalyze these functional units and generate decoders, executors,\nmemory units, etc (see \u003c\u003cgenerators\u003e\u003e). These generated functions will\nbe used not only in the specification in\nhttps://github.com/sifive/ProcKami[ProcKami], but also to generate\ncomplex microarchitecture implementations (such as the\nhttps://en.wikipedia.org/wiki/Out-of-order_execution[out-of-order\nprocessor]). This makes formal verification of these complex\nmicroarchitectures easier, as they share the same generated functions\n(such as decoder, executor, etc) with the specification they must be\nproven against. For actual implementations, it is important that each\nfunctional unit handles several instructions, where the inputs and\noutputs for the functional units are transformed based on the\ninstruction. This organization of separating the semantics of an\ninstruction into a *ExecContextPkt* transformer to feed a functional\nunit, the generic functionality of the functional unit and a\ntransformation of the output of the functional unit to an\n*UpdateContextPkt* does not overly impose any burden on the\nreadability or the understandability of the RISC-V ISA specification,\nbut eases the formal verification cost of implementations significantly.\n\n=== Top-level directory and files [[generators]]\nThese files take the tables in the\n https://github.com/sifive/ProcKami/tree/master/FuncUnits[ProcKami/FuncUnits]\n directory and produce several useful functions like the\n https://github.com/sifive/ProcKami/blob/master/Decoder.v[decoder],\n https://github.com/sifive/ProcKami/blob/master/RegReader.v[reg-reader],\n https://github.com/sifive/ProcKami/blob/master/Executer.v[executor], etc. These\n functions are all assembled in\n https://github.com/sifive/ProcKami/tree/master/ProcessorCore.v[ProcessorCore.v]\n to create a formal specification of the processor.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsifive%2Friscvspecformal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsifive%2Friscvspecformal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsifive%2Friscvspecformal/lists"}