├── Forvis.md ├── GRIFT.md ├── Kami.md ├── README.md ├── Sail.md ├── comparison_table.md ├── riscv-formal-isa-responses-all.pdf ├── riscv-formal-isa-responses-summary.pdf └── riscv-plv.md /Forvis.md: -------------------------------------------------------------------------------- 1 | # RISC-V ISA Formal Specification 2 | 3 | ## Name 4 | 5 | Forvis ("FOrmal RiscV Specification") 6 | 7 | ---------------------------------------------------------------- 8 | ## Authors (with institutions) 9 | 10 | Rishiyur S. Nikhil, Bluespec, Inc. 11 | 12 | ---------------------------------------------------------------- 13 | ## Spec sources snapshot (e.g. URL to github repo) 14 | 15 | [https://github.com/rsnikhil/Forvis_RISCV-ISA-Spec](https://github.com/rsnikhil/Forvis_RISCV-ISA-Spec) 16 | 17 | ---------------------------------------------------------------- 18 | ## Spec sources live development (e.g. URL to github repo) 19 | 20 | [https://github.com/rsnikhil/Forvis_RISCV-ISA-Spec](https://github.com/rsnikhil/Forvis_RISCV-ISA-Spec) 21 | 22 | ---------------------------------------------------------------- 23 | ## Licence 24 | 25 | MIT License 26 | 27 | ---------------------------------------------------------------- 28 | ## Metalanguage (including brief explanation of the metalanguage used) 29 | 30 | Haskell, the well known pure functional language with expressive type 31 | system and strong static typechecking. More at 32 | [haskell.org](https://www.haskell.org). 33 | 34 | ---------------------------------------------------------------- 35 | ## Dependencies on what tools 36 | 37 | To build and run the spec as a RISC-V simulator, without 38 | floating-point (RISC-V "F" and "D" extensions), you just need: 39 | 40 | - `ghc` Haskell compiler. Available as standard package install on most 41 | Unix-like systems (e.g., `apt-get install ghc`). More at 42 | [haskell.org](https://www.haskell.org). 43 | 44 | - Haskell's `elf` library for reading ELF compiled RISC-V binaries. 45 | 46 | To run the supplied Python program that runs regression tests over all the standard ISA tests: 47 | 48 | - Python 3 (version 3.6 or later preferred) 49 | 50 | If you include Floating Point in your build, the following git 51 | submodules will have to be pulled: 52 | 53 | - Galois, Inc's [Haskell wrapper](https://github.com/GaloisInc/softfloat-hs.git) 54 | for Berkeley's "softfloat" (see next) 55 | 56 | - U.C.Berkeley's "softfloat" IEEE floating point emulation library: 57 | [softfloat](https://github.com/ucb-bar/berkeley-softfloat-3.git) and 58 | [testfloat](https://github.com/ucb-bar/berkeley-testfloat-3.git) 59 | 60 | ---------------------------------------------------------------- 61 | ## Tool ecosystem: what other work has been/is being done with those tools 62 | 63 | - Haskell is a general purpose language used widely in thousands of 64 | applications. `ghc` is the most commonly used Haskell compiler. 65 | 66 | - Python is a general purpose language used widely in thousands of applications. 67 | 68 | - Berkeley "softfloat" is written in C/C++ and is used widely in 69 | industry and academia to emulate IEEE floating point operations and as 70 | a "reference model" for IEEE floating point. 71 | 72 | ---------------------------------------------------------------- 73 | ## Motivation (a few sentences explaining for what the authors have developed this spec) 74 | 75 | Highest priority: 76 | 77 | - Readability by people not familiar with formal 78 | specifications or with Haskell, and who simply want to consult a 79 | formal spec to get precise answers to questions about ISA 80 | semantics. Typical audience: assembly language prorammers, 81 | compiler writers, CPU hardware designers, RISC-V compliance-test 82 | writers, and so on. 83 | 84 | Other standard motivations: 85 | 86 | - Ease of use in formal reasoning with simple connection to other 87 | formal tools (e.g., proof assistants, theorem provers) 88 | - Ease of building and execution as a simulator, and use as "Golden 89 | Reference Model" for Compliance Testing and Tandem Verification. 90 | - Ease of extension for formalization of new ISA features 91 | - Ease of extension to plug in formalizations of I/O devices and accelerators 92 | - Same spec code usable both in simple, sequential 93 | (one-instruction-at-a-time) case as well as more complex 94 | concurrency (to model pipelines, copies of data in 95 | caches/store-buffers, wide-issue, out-of-order, multi-core, ...) 96 | 97 | ---------------------------------------------------------------- 98 | ## Current functional coverage (what's modelled now, in RISC-V code and in English) 99 | 100 | ### Base ISA and extensions 101 | 102 | Base ISAs: RV32I, RV64I 103 | 104 | Standard extensions: 105 | M (Integer Mult/Div), 106 | A (Atomics), 107 | FD (single- and double-precision floating point), 108 | C (Compressed) 109 | 110 | ### Privilege levels 111 | 112 | Privilege levels: M (machine), U (User) and S (Supervisor). 113 | 114 | Virtual Memory Schemes: Sv32, Sv39, Sv48 115 | 116 | Interrupts: External, Timer and Software interrupts, including 117 | interrupt delegation. Non-Maskable Interrupts. 118 | 119 | Forvis can model simultaneous RV32 and RV64 (MISA.MXL, MSTATUS.SXL and 120 | MSTATUS.UXL can be set to different values, even dynamically). 121 | 122 | ---------------------------------------------------------------- 123 | ## Current specification of assembly syntax and encoding 124 | 125 | Forvis does not do anything with respect to assembly syntax, nor are there any plans to do so. 126 | 127 | Forvis executes with 32-bit (standard) and 16-bit (C) RISC-V 128 | instructions in memory; the simulator has support to load memory from 129 | ELF files and Memory-Hex (standard Verilog format) files. 130 | 131 | Forvis has internal data structures for decoded instructions. Decoder 132 | and encoder functions to/from 32b/16b representations are provided. 133 | 134 | ---------------------------------------------------------------- 135 | ## Current treatment of concurrency 136 | 137 | None as yet. 138 | 139 | It has always been our objective that the same spec source code can be 140 | *interpreted* in different ways, either (1) sequentially 141 | (one-instruction-at-a-time) or (2) concurrently (to model pipelines, 142 | copies of data in caches/store-buffers, wide-issue, out-of-order, 143 | multi-core, ...). 144 | 145 | Currently, compilation and execution as a Haskell program provides (1). 146 | 147 | For (2), we have a specific plan for a concurrent interpreter, but 148 | implementing this is future work. This includes linking it to 149 | RISC-V's weak memory models (RVWMO and ZTSO). 150 | 151 | ---------------------------------------------------------------- 152 | ## Current treatment of floating-point 153 | 154 | Uses U.C.Berkeley's "softfloat" IEEE floating point emulation library 155 | (which is written in C/C++), accessed via Galois, Inc's Haskell 156 | wrapper. See links above in Section "Dependencies on what tools" 157 | 158 | ---------------------------------------------------------------- 159 | ## Current capabilities (what the specification and associated tooling generates and enables) 160 | 161 | ### Emulation 162 | 163 | Forvis is written in standard, vanilla Haskell. It can be compiled 164 | with `ghc`, the standard Haskell compiler, to produce a simulator 165 | implementing sequential, one-instruction-at-a-time semantics. The 166 | simulator can load memory from run ELF or Mem-hex files, and run the 167 | RISC-V program. The "system" setup provided with Forvis includes: 168 | 169 | - A Boot ROM 170 | - A Memory 171 | - Implementation of MTIME and MTIMECMP memory-mapped timer locations, 172 | capable of generating timer interrupts. 173 | - Implementation of a memory-mapped "software-interrupt" location, 174 | capable of generating software interrupts. 175 | - A UART (modeling a standard NS16550 UART) through which the CPU can do console IO. 176 | 177 | With verbosity 1, execution will provide an instruction trace 178 | (instruction number, PC, instruction, decoded instruction). 179 | 180 | With verbosity 2, execution will, in addition, produce a dump of the 181 | full processor state (not memory) after each instruction (PC, GPRs, FPRs, GPRs). 182 | 183 | Forvis contains various simulation aids to signal "end of simulation", 184 | such as watching a "tohost" memory address (this is how the ISA tests 185 | are written), stopping at a BREAK instruction, stopping after a given 186 | number of instructions have executed, etc. 187 | 188 | There is also a facility to dump out a memory region at "end of 189 | simulation" (e.g., this is how Compliance Tests work). 190 | 191 | Speed: Linux kernel boot takes about 40 minutes on a fast laptop. 192 | FreeRTOS kernel boot takes just a few seconds. This is very fast for 193 | a formal spec; slower than purpose-built C/C++ simulators such as 194 | Spike; and much faster than RTL simulation of most CPU 195 | implementations. 196 | 197 | ### Use as test oracle in tandem verification 198 | 199 | Bluespec uses Forvis as a "Golden Reference Model" for Tandem 200 | Verification of its hardware CPU implementations. The hardware 201 | produces a "tandem verification trace", and a variant packaging of 202 | Forvis checks this, instruction by instruction, for correctness. This 203 | includes interrupt-handling. 204 | 205 | ### Theorem-prover definitions that support proof 206 | 207 | Researchers at U.Penn are currently using Forvis as a basis for their 208 | work to formally prove correctness of their hardware implementations 209 | as well as their RISC-V security extensions. 210 | 211 | ### Use in documentation 212 | 213 | A general-purpose Python tool is provided in the Doc/ directory to 214 | extract labelled fragments of the spec Haskell source code and to wrap 215 | them in LaTeX environments. Currently this facility is used in 216 | producing the "Forvis Reading and Extension Guide" (in the Doc 217 | directory). In principle this facility could also be used to insert 218 | formal spec code fragments into the official English-language spec 219 | docs. 220 | 221 | ### Use in test generation 222 | 223 | Forvis has not yet been used by the author for automated test generation. 224 | 225 | Since it contains a data type for decoded instructions, it should be 226 | possible to use Haskell's "QuickCheck" facility to automatically 227 | generate test instruction sequences, but this is still future work. 228 | 229 | Researchers at U.Penn are using Forvis for test generation, and for 230 | formal analysis of security properties in their RISC-V extension for 231 | security. 232 | 233 | ### Use for concurrency-model litmus test evaluation 234 | 235 | None yet. 236 | 237 | Concurrency in Forvis is still future work. 238 | 239 | ### Other 240 | 241 | We expect that U.Penn's `hs-to-coq` tool can be used to translate 242 | Forvis into "very similar" Coq for subsequent formal analysis and 243 | manipulation in Coq. 244 | 245 | A standalone parser for Forvis, written in in Haskell, is in progress. 246 | This will read Forvis source code (which is in Haskell syntax) and 247 | dump out an abstract syntax tree, probably in Lisp-like S-Expression 248 | format. This parser can also be used to check that Forvis is 249 | restricted to our ``extremely elementary'' subset of Haskell. 250 | 251 | ---------------------------------------------------------------- 252 | ## Current test coverage 253 | 254 | Forvis passes all ISA tests for the supported features (RV32/RV64 255 | IMAFDC, Privilege levels M/S/U). A way to run all ISA tests is 256 | provided in the repository. 257 | 258 | ### RISC-V compliance tests 259 | 260 | Forvis passes all currently available tests in the Compliance Suite. 261 | A way to run all Compliance tests is provided in the repository. 262 | 263 | ### OS boot testing 264 | 265 | Forvis boots a Linux kernel compiled for RV64IMASU. This example is 266 | provided in the repository. It takes about 40 minutes on a fast laptop. 267 | 268 | Forvis boots a FreeRTOS kernel compiled for RV32IMACU. This example 269 | is provided in the repository. It takes just a few seconds. 270 | 271 | ### Concurrency litmus test testing 272 | 273 | None, to date (awaits writing the concurrent interpreter for the Forvis spec code). 274 | 275 | ### Other 276 | 277 | Miscellaneous programs compiled from C using the RISC-V toolchain. 278 | 279 | ---------------------------------------------------------------- 280 | ## Plans for future functional coverage 281 | 282 | - Basic functionality: Since Forvis already implements both the 283 | standard bases (RV32I/RV64I) all the standard extensions (IMAFDC), 284 | all the standard privilege levels (M, S, U) and all the standard 285 | virtual memory schemes (Sv32, Sv39, Sv48), there are no plans to 286 | add more functionality. 287 | 288 | - We plan to develop the concurrent interpreter to model concurrency, 289 | as explained in Section "Current treatment of concurrency" 290 | 291 | - A work-in-progress is "RIFFL" (RISC-V Formal Feature List) which 292 | captures all the choices allowed for implementations, such as: 293 | 294 | - whether or not to trap on misaligned memory accesses 295 | - treatment of A and D bits in Page Table Entries 296 | - treatment of WARL ("Write Any Read Legal") fields in CSRs 297 | - ... and so on. 298 | 299 | Currently Forvis makes a specific choice regarding each of these. 300 | With RIFFL, Forvis will be parameterized to accommodate any 301 | profile of choices. 302 | 303 | ---------------------------------------------------------------- 304 | ## Plans for long-term access, maintenance, etc. 305 | 306 | Open source, MIT license, on GitHub. 307 | 308 | The tool is used by the author and his company (Bluespec, Inc.) for 309 | tandem verification, as a golden reference model to check Bluespec's 310 | hardware designs, for coverage measurement, and more. Bluespec and 311 | the author intend to maintain this for the foreseeable future. 312 | 313 | ---------------------------------------------------------------- 314 | ## Example instructions 315 | 316 | ### ITYPE (or ADDI) 317 | 318 | Part of the data structure for decoded instructions: 319 | 320 | data Instr_I = LUI GPR_Addr InstrField -- rd, imm20 321 | | ADDI GPR_Addr GPR_Addr InstrField -- rd, rs1, imm12 322 | | ... 323 | 324 | Opcode family of which ADDI is a member: 325 | 326 | opcode_OP_IMM = 0x13 :: InstrField -- 7'b_00_100_11 327 | 328 | Sub-opcode definition for ADDI: 329 | 330 | -- opcode_OP_IMM sub-opcodes 331 | funct3_ADDI = 0x0 :: InstrField -- 3'b_000 332 | 333 | Part of the decode function for ADDI: 334 | 335 | m_instr_I 336 | | opcode==opcode_OP_IMM, funct3==funct3_ADDI = Just (ADDI rd rs1 imm12_I) 337 | 338 | Semantic functions for ADDI (dispatches to a shared function for `OP_IMM` 339 | 340 | exec_ADDI is_C (ADDI rd rs1 imm12) mstate = exec_OP_IMM alu_add is_C rd rs1 imm12 mstate 341 | 342 | Semantic functions for `OP_IMM` functions 343 | 344 | exec_OP_IMM :: (Int -> Integer -> Integer -> Integer) -> Bool -> GPR_Addr -> GPR_Addr -> InstrField -> Machine_State -> Machine_State 345 | exec_OP_IMM alu_op is_C rd rs1 imm12 mstate = 346 | let 347 | xlen = mstate_xlen_read mstate 348 | rs1_val = mstate_gpr_read rs1 mstate 349 | 350 | s_imm = sign_extend 12 xlen imm12 351 | 352 | rd_val = alu_op xlen rs1_val s_imm 353 | mstate1 = finish_rd_and_pc_incr rd rd_val is_C mstate 354 | in 355 | mstate1 356 | 357 | 358 | ### SRET 359 | 360 | In Forvis a single function `exec_xRET` is used for MRET, SRET and URET: 361 | 362 | type Spec_Instr_Priv = Bool -> Instr_Priv -> Machine_State -> Machine_State 363 | -- is_C instr_Priv mstate mstate' 364 | 365 | exec_xRET :: Instr_32b -> Spec_Instr_Priv 366 | exec_xRET instr_32b is_C instr_Priv mstate = 367 | let 368 | is_MRET = (instr_Priv == MRET) 369 | is_SRET = (instr_Priv == SRET) 370 | is_URET = (instr_Priv == URET) 371 | priv = mstate_priv_read mstate 372 | is_legal = (( is_MRET && (priv == m_Priv_Level)) 373 | || (is_SRET && (priv >= s_Priv_Level)) 374 | || (is_URET && (priv >= u_Priv_Level))) 375 | 376 | mstatus = mstate_csr_read csr_addr_mstatus mstate 377 | tsr_fault = (is_SRET && (priv == s_Priv_Level) && (testBit mstatus mstatus_tsr_bitpos)) 378 | (mpp,spp,mpie,spie,upie,mie,sie,uie) = mstatus_stack_fields mstatus 379 | rv = mstate_rv_read mstate 380 | misa = mstate_csr_read csr_addr_misa mstate 381 | 382 | mstate3 = if (tsr_fault) 383 | then 384 | let tval = instr_32b 385 | in 386 | finish_trap exc_code_illegal_instruction tval mstate 387 | 388 | else 389 | let 390 | -- New 'previous-priv' is U if supported, else M 391 | new_pp = if (misa_flag misa 'U') then u_Priv_Level else m_Priv_Level 392 | 393 | -- New priv, and new priv stack 394 | (priv',mpp',spp') 395 | -- From M 396 | | (priv == m_Priv_Level) && is_MRET && (mpp == m_Priv_Level) = (m_Priv_Level, new_pp, spp) 397 | | (priv == m_Priv_Level) && is_MRET && (mpp == s_Priv_Level) = (s_Priv_Level, new_pp, spp) 398 | | (priv == m_Priv_Level) && is_MRET && (mpp == u_Priv_Level) = (u_Priv_Level, new_pp, spp) 399 | 400 | | (priv == m_Priv_Level) && is_SRET && (spp == s_Priv_Level) = (s_Priv_Level, new_pp, spp) 401 | | (priv == m_Priv_Level) && is_SRET && (spp == u_Priv_Level) = (u_Priv_Level, new_pp, spp) 402 | 403 | | (priv == m_Priv_Level) && is_URET = (u_Priv_Level, new_pp, spp) 404 | 405 | -- From S 406 | | (priv == s_Priv_Level) && is_SRET && (spp == s_Priv_Level) = (s_Priv_Level, mpp, new_pp) 407 | | (priv == s_Priv_Level) && is_SRET && (spp == u_Priv_Level) = (u_Priv_Level, mpp, new_pp) 408 | 409 | | (priv == s_Priv_Level) && is_URET = (u_Priv_Level, mpp, new_pp) 410 | 411 | -- From U 412 | | (priv == u_Priv_Level) && is_URET = (u_Priv_Level, mpp, spp) 413 | 414 | -- New interrupt-enable stack in new mstatus 415 | (mpie',spie',upie',mie',sie',uie') | is_MRET = ( 1, spie, upie, mpie, sie, uie) 416 | | is_SRET = (mpie, 1, upie, mie, spie, uie) 417 | | is_URET = (mpie, spie, 1, mie, sie, upie) 418 | mstatus' = mstatus_upd_stack_fields mstatus (mpp',spp',mpie',spie',upie',mie',sie',uie') 419 | 420 | -- New PC 421 | pc1 | is_MRET = mstate_csr_read csr_addr_mepc mstate 422 | | is_SRET = mstate_csr_read csr_addr_sepc mstate 423 | | is_URET = mstate_csr_read csr_addr_uepc mstate 424 | pc2 | (rv == RV32) = (pc1 .&. 0xFFFFFFFF) 425 | | True = pc1 426 | 427 | -- Update arch state 428 | mstate1 = mstate_csr_write csr_addr_mstatus mstatus' mstate 429 | mstate2 = mstate_priv_write priv' mstate1 430 | in 431 | finish_pc pc2 mstate2 432 | in 433 | mstate3 434 | 435 | ---------------------------------------------------------------- 436 | ## Documentation for model and tools 437 | 438 | ### snapshot of "Reading Guide", for those who just want to read it like an ISA manual 439 | 440 | Please see [Forvis Reading and Extension Guide](https://github.com/rsnikhil/Forvis_RISCV-ISA-Spec/blob/master/Doc/forvis_reading_guide.pdf) 441 | 442 | The code, together with this reading guide, is intended to be readable 443 | on its own, without any prior knowledge of Haskell. 444 | 445 | ### snapshot of "How to Compile/Run Guide" for those who want to execute a model on programs (ISA tests, Compliance tests, other programs) 446 | 447 | Please see [README](https://github.com/rsnikhil/Forvis_RISCV-ISA-Spec/blob/master/Doc/README) in the Forvis repository for detailed instructions on how to build and run Forvis on ISA tests, on the Compliance Test Suite, on some C programs, on a Linux kernel, and on a FreeRTOS kernel. 448 | 449 | The Linux kernel boot takes about 40 minutes on a fast laptop. 450 | 451 | The FreeRTOS kernel boot takes a few seconds. 452 | 453 | ### snapshot of "How to Extend Guide" for those who want to extend the model to capture new ISA extensions/experiments. 454 | 455 | Please see [Forvis Reading and Extension Guide](https://github.com/rsnikhil/Forvis_RISCV-ISA-Spec/blob/master/Doc/forvis_reading_guide.pdf) in the Forvis repository. 456 | -------------------------------------------------------------------------------- /GRIFT.md: -------------------------------------------------------------------------------- 1 | # RISC-V ISA Formal Specification 2 | 3 | ## Name 4 | 5 | GRIFT - Galois RISC-V ISA Formal Tools 6 | 7 | ## Authors 8 | 9 | Ben Selfridge, Galois Inc. 10 | 11 | ## Spec sources snapshot 12 | 13 | https://github.com/GaloisInc/grift/ 14 | 15 | ## Spec sources live development (e.g. URL to github repo) 16 | 17 | https://github.com/GaloisInc/grift/ 18 | 19 | ## Licence 20 | 21 | GNU Affero General Public License v3.0 22 | 23 | ## Metalanguage (including brief explanation of the metalanguage used) 24 | 25 | GRIFT is written in Haskell, a strongly-typed functional programming 26 | language. 27 | 28 | ## Dependencies on what tools 29 | 30 | - Various standard Haskell libraries 31 | - Softfloat C library (http://www.jhauser.us/arithmetic/SoftFloat.html) 32 | 33 | ## Tool ecosystem: what other work has been/is being done with those tools 34 | 35 | GRIFT is a part of the BESSPIN tool suite, currently being developed at 36 | Galois. BESSPIN is a collection of tools to understand, explore, and reason 37 | about the correctness and security of a hardware product line. GRIFT is used 38 | within BESSPIN as the golden ISA specification. Currently, it is used for 39 | coverage evaluation of the RISC-V Compliance Working Group's evolving compliance 40 | test suite; in this capacity, it has exposed several shortcomings in many of 41 | those hand-written tests. The GRIFT library will also be used for custom 42 | correctness test generation, based on a particular RISC-V platform 43 | configuration, as well as tandem verification, in joint work with Bluespec. 44 | 45 | ## Motivation 46 | 47 | Goals that drove the development of the GRIFT RISC-V specification: 48 | - Written in a practical programming language capable of providing a strong 49 | theoretical foundation (Haskell) 50 | - Elegant, bidirectional specification of instruction encodings 51 | - Customizable spec, parameterized over the RISC-V feature model (RV[32|64|128] 52 | [I|M|A|F|D|C]) 53 | - Deeply-embedded instruction semantics, written in an embedded domain-specific 54 | language (DSL) 55 | - Designed to be highly compatible with existing tools and frameworks 56 | 57 | ## Current functional coverage 58 | 59 | - RV32/64GC 60 | - Instruction encodings 61 | - Semantics 62 | - Privilege mode M (no S/U yet, that will come Spring 2019) 63 | 64 | ## Current specification of assembly syntax and encoding 65 | 66 | GRIFT does not have a RISC-V assembly parser, but it does have a pretty-printer 67 | that emits individual lines of assembly for a given instruction. Binary 68 | instruction encodings are specified declaratively; the "format" of the 69 | instruction, which determines exactly which bits are "opcode" vs. "operand" 70 | bits, is contained as part of the type of the instruction/opcode, and this same 71 | format is used to determine how to handle encoding and decoding for that 72 | instruction. The mechanism that performs the encoding/decoding, based on Haskell 73 | `lens`es, is handled by our `bv-sized` library (open source on Github). 74 | 75 | ## Current treatment of concurrency 76 | 77 | Concurrency is not currently handled by GRIFT, and as of right now, simulation 78 | with GRIFT is entirely deterministic. We can model concurrency in a 79 | straightforward way in simulation by modifying our step function to produce a 80 | list of potential next-states rather than just one; however, what would be more 81 | compelling and usable would be to define the RISC-V memory model with the 82 | embedded GRIFT semantics DSL (in much the same way as the instructions semantics 83 | themselves are defined). We have not explored such an approach in depth, but it 84 | is very likely an area of further development that will be explored at some 85 | point here at Galois. 86 | 87 | ## Current treatment of floating-point 88 | 89 | Floating point operations are represented in our DSL as symbolic operations on 90 | bitvectors (F32Add, F64Sqrt, etc.), and are interpreted in simulation foreign 91 | function calls to the Berkeley Softfloat library (referenced above). 92 | 93 | ## Current capabilities 94 | 95 | - Haskell library with RISC-V base ISA and extensions, with all instruction encodings 96 | and semantics for RV32/64GC 97 | - Command-line documentation tool (`grift-doc`) 98 | - Command-line simulation and coverage tool (`grift-sim`) 99 | 100 | ### Emulation 101 | 102 | GRIFT is a Haskell library and can be incorporated as such into any 103 | Haskell codebase. However, it also comes with an executable `grift-sim`, runs 104 | ELF files targeting any standard RISC-V configuration (any of the G/C 105 | extensions, and 32- or 64-bit). `grift-sim` also has been engineered to keep 106 | track of, not only which instructions are covered during simulation, but also 107 | which semantic branches of each instruction are executed. For instance, if an 108 | instruction branches based on whether a particular register identifier is equal 109 | to 0 or not, `grift-sim` will report whether both of those branches have 110 | actually been explored by a particular test or suite of tests. 111 | 112 | ### Use as test oracle in tandem verification 113 | 114 | GRIFT is currently being incorporated into Bluespec's Security Verification 115 | Factory (SVF) as the golden reference model for tandem verification. That work 116 | is still in progress. 117 | 118 | ### Theorem-prover definitions that support proof 119 | 120 | None; however, because the semantics are written in a Haskell-embedded DSL, it 121 | is straightforward to emit theorem-prover definitions for any given target 122 | environment (Coq, ACL2, etc.). 123 | 124 | ### Use in documentation 125 | 126 | GRIFT can automatically generate documentation for each instruction; right now 127 | it is pure textual form via the command-line tool `grift-sim`, but it would be 128 | straightforward to emit LaTeX as well. The semantics definitions include textual 129 | descriptions of the behavior of each instruction, and the semantics themselves 130 | are also pretty-printed so that the user can visually inspect the DSL behavioral 131 | specification of the instruction, again using the command-line tool. 132 | 133 | ### Use in test generation 134 | 135 | None yet, although GRIFT is ideally suited for such given its internal 136 | representation of the instruction semantics. Galois is well-versed in the 137 | problem of code generation, and we have also coordinated with Cambridge 138 | regarding potentially combining our efforts with theirs. 139 | 140 | ### Use for concurrency-model litmus test evaluation 141 | 142 | None. 143 | 144 | ## Current test coverage 145 | 146 | ### RISC-V compliance tests 147 | 148 | Currently, the only standard RISC-V compliance tests that GRIFT fails are the 149 | ones that make certain assumptions about a particular system configuration; for 150 | example, misaligned loads and stores are currently allowed in GRIFT without any 151 | exceptions raised, but the compliance test assumes an exception will be raised 152 | on a misaligned memory access. 153 | 154 | ### OS boot testing 155 | 156 | We have not attempted to boot Linux yet as we will not have funding for this 157 | work for a few months, although this will be tackled at some point in the near 158 | future. 159 | 160 | ### Concurrency litmus test testing 161 | 162 | None. 163 | 164 | ### Other 165 | 166 | We pass all the standard tests in Berkeley's riscv-tests suite. 167 | 168 | ## Plans for future functional coverage 169 | 170 | - Full privileged architecture, with associated parameterizability 171 | - Automatic test generation via GRIFT semantics and machine code synthesis 172 | (hopefully to be incorporated in the Compliance WG's infrastructure 173 | - Integration with at least one theorem prover 174 | - Integration with HDLs (e.g., emit verilog code from semantics) 175 | - Concurrency -- nondeterminism in simulation in combination with precise 176 | specification of RISC-V memory model 177 | - Linux/FreeRTOS boot 178 | 179 | ## Plans for long-term access, maintenance, etc. 180 | 181 | - GRIFT will be maintained in-house at Galois, with Ben Selfridge as the primary 182 | developer & maintainer. It was designed in part to be highly compatible with 183 | our codebases, and has become the de facto RISC-V specification 184 | here. Therefore, we will be expanding and maintaining it for our own internal 185 | purposes. 186 | 187 | ## Example instructions 188 | 189 | ### ADDI 190 | 191 | Source code semantics: 192 | ``` 193 | comment "Adds the sign-extended immediate to register x[rs1] and writes the result to x[rd]." 194 | comment "Arithmetic overflow is ignored." 195 | 196 | rd :< rs1 :< imm12 :< Nil <- operandEs 197 | 198 | let x_rs1 = readReg rs1 199 | let res = x_rs1 `addE` (sextE imm12) 200 | 201 | assignGPR rd res 202 | incrPC 203 | ``` 204 | 205 | Semantics as displayed by `grift-doc` documentation tool: 206 | ``` 207 | add semantics 208 | ===================== 209 | 210 | Adds register x[rs2] to register x[rs1] and writes the result to x[rd]. 211 | Arithmetic overflow is ignored. 212 | IF rd == 0x0 213 | THEN 214 | ELSE 215 | x[rd] := (if rs1 == 0x0 then 0x0 else x[rs1]) + (if rs2 == 0x0 then 0x0 else x[rs2]) 216 | pc := pc + step 217 | ``` 218 | 219 | ## Documentation for model and tools 220 | 221 | ### Reading Guide 222 | 223 | See [docs/Reading.md](https://github.com/GaloisInc/grift/blob/master/docs/Reading.md) 224 | for a discussion of how to read GRIFT as an ISA manual. 225 | 226 | ### Compiling/Running 227 | 228 | See [README.md](https://github.com/GaloisInc/grift/blob/master/README.md) for 229 | information on how to build and run GRIFT on your system. 230 | 231 | ### Extending 232 | 233 | See [docs/Extend.md](https://github.com/GaloisInc/grift/blob/master/docs/Extend.md) 234 | for a discussion of how to extend GRIFT with a new ISA extension. 235 | -------------------------------------------------------------------------------- /Kami.md: -------------------------------------------------------------------------------- 1 | # RISC-V ISA Formal Specification 2 | 3 | ## Name 4 | 5 | RISC-V ISA Spec in Kami 6 | 7 | ## Authors 8 | 9 | 1. Murali Vijayaraghavan (SiFive) 10 | 2. Larry Lee (SiFive) 11 | 12 | ## Spec sources snapshot 13 | 14 | https://github.com/sifive/RiscvSpecFormal 15 | 16 | Note that the master branch of the RISC-V Kami Spec only presents the current stable release version. 17 | 18 | ## Spec sources live development 19 | 20 | https://github.com/sifive/RiscvSpecFormal/ProcKami 21 | 22 | The idea is to keep the top-level git repository always stable, and link it to the stable version of the submodule constantly. 23 | 24 | ## Licence 25 | 26 | Apache 2.0 27 | 28 | ## Metalanguage 29 | 30 | The RISC-V Kami Spec is a RISC-V processor model written in Gallina and Ltac. Gallina is a functional programming language that uses higher order types to express logical assertions and proofs. Ltac is a procedural macro language used principlally to write proofs that compiles into Gallina. Using Gallina and Ltac, programmers may describe algorithms, express claims about those algorithms, and write proofs that support those claims. Developments written in Gallina and Ltac can be compiled and verified using Coq, a general purpose proof assistant. 31 | 32 | The RISC-V Kami Spec uses the Kami library to model a RISC-V processor. The Kami library provides a domain specific language designed to describe and model digital circuits. Originally developed at MIT, SiFive has extended the Kami library to include a Verilog code generator that can generate Verilog code that represents circuits described using Kami's DSL. The RISC-V processor presented here uses Kami's DSL. 33 | 34 | The complete processor model includes register and memory modules written in Verilog. These modules can be linked to the Verilog code generated from the Kami model to produce a fully functioning RISC-V processor model in Verilog. 35 | 36 | ## Dependencies on what tools 37 | 38 | The RISC-V Kami Spec relies on the following tools/libraries: 39 | 40 | 1. Coq 8.9.x 41 | 2. Kami 42 | 3. Verilator >= 4.014, the master branch on the git tree as of March 29, 2019 -- it contains a critical patch for 64-bit systems (for compiling and simulating verilog) 43 | 4. BBV (Bedrock Bit Vector) -- it implements the bit-vector library in Coq 44 | 5. coq-record-update -- it implements notation for updating structures in place 45 | 6. clang (C-compiler that can run verilator generated C code fast) 46 | 7. GHC 8.4.x (Haskell compiler to generate verilog) 47 | 48 | ## Tool ecosystem: what other work has been/is being done with those tools 49 | 50 | The product of over 30 years of development, Coq is a leading proof assistant and is under active development. It has been used to develop formally verified C compilers (see the CompCert project), and to prove numerous mathematical theorems. 51 | 52 | The result of over 5 years of development, Kami was created at MIT to model digital circuits and has since been developed by SiFive. It has been used to model and verify processors developed at SiFive. 53 | 54 | The BBV and coq-record-update libraries are fairly small libraries maintained by MIT. 55 | 56 | The clang compiler, verilator and GHC compiler are all fairly mature open source tools. 57 | 58 | ## Motivation 59 | 60 | SiFive's goal is to do more than just create a functional model of a RISC-V processor. Rather, our goal is to use Coq's general purpose theorem proving features to formalize the RISC-V semantics, to validate our implementation against these semantics, and to verify the correctness of our model implementation using certified programming techniques. 61 | 62 | Using Coq and Kami, we can do more than create programs that simulate RISC-V processors; we can create a framework for abstractly representing and reasoning over the behavior of systems using RISC-V. 63 | 64 | ## Current functional coverage 65 | 66 | ### Base ISA and extensions 67 | 68 | The current model covers RV-IMACF. However, the current implementation can easily be extended to support a larger subset of the RISC-V instruction set. Rather than hardcode the interpretation and behavior of every individual RISC-V instruction, the current model uses an extensible instruction database that may be expanded with little to no modification of the model's core. The resulting modularity means that, once the core has become stable, our model can be extended and modified easily to track changes to RISC-V spec. 69 | 70 | ### Privilege levels 71 | It currently supports only user privilege level, with Machine and Supervisor privilege levels in unstable branches. 72 | 73 | ### Parameterisation of the model 74 | The extensible instruction database is written in a parameterized manner, which can be instantiated to 32-bits, 64-bits, 128-bits or any other bit-widths for data path. It also supports extensions using a parameter table that lists all the extensions to generate in the formal model. 75 | 76 | ## Current specification of assembly syntax and encoding 77 | 78 | The specification is written as a database, i.e., a list of entries in Gallina, with the specification of each instruction written as a Kami LetExpression. The syntax is discussed in greater detail below. 79 | 80 | ## Current treatment of concurrency 81 | 82 | The implementation model presented here consists of a single RISC-V processor with plans to extend it to multicore systems, implementing the most relaxed version of the memory model. In fact, since Kami is a general purpose hardware specification language, it is trivial to design arbitrarily complex concurrent hardware systems in Kami (see the Multicore system + hierarchical caches written in Kami in the ICFP 2018 Kami paper). 83 | 84 | ## Current treatment of floating-point 85 | 86 | We currently support the entire floating-point instruction set (RVF). The floating point unit is completely implemented in Kami. The unstable version also contains RVD (double-precision floating point). 87 | 88 | ## What the specification and associated tooling generates and enables 89 | 90 | Our model can be compiled to Verilog. Accordingly, it can be simulated and synthesized using standard tools. 91 | 92 | ### Emulation 93 | 94 | Since it generates verilog, verilator can be used to run the generated verilog 95 | 96 | ### Use as test oracle in tandem verification 97 | It prints out the instruction packets through various stages (i.e. Fetch, Decode, Execute, Memory, Writeback, even though these stages all together happen in one clock cycle). This trace can be used in tandem verification. 98 | 99 | ### Theorem-prover definitions that support proof 100 | 101 | Our processor model is implemented in Kami. Accordingly, it's behavior is immediately verifiable using Coq. We have developed an elaborate ecosystem for Kami in Coq that includes several tactics to perform proof search and several general theorems about the semantics of Kami that helps in proving designs to be equivalent to the formal specification. In addition, various tools and utilities exist for export Coq definitions and theorems into other proof assistants. 102 | 103 | ### Use in documentation 104 | 105 | Our model's instruction database will provide a description of every instruction in the RISC-V spec. Anyone looking to determine the behavior of a given RISC-V instruction will eventually be able to refer to the instruction database and find a description of its semantics. 106 | 107 | [//]: # "### Use in test generation" 108 | 109 | [//]: # "### Use for concurrency-model litmus test evaluation" 110 | 111 | ### Current test coverage 112 | 113 | It passes all the "rv32u.-p-.*" tests in riscv-tests 114 | 115 | ### RISC-V compliance tests 116 | 117 | We have a target in the compliance test suite. 118 | https://github.com/riscv/riscv-compliance/tree/master/riscv-target/sifive-formal 119 | 120 | [//]: # "### OS boot testing" 121 | 122 | [//]: # "### Concurrency litmus test testing" 123 | 124 | [//]: # "### Other" 125 | 126 | ## Plans for future functional coverage 127 | 128 | Our aspiration is to eventually cover the entire RISC-V instruction set, including both supervisor and machine modes. 129 | 130 | ## Plans for long-term access, maintenance, etc. 131 | 132 | SiFive plans to sponsor the RISC-V Kami spec for the indefinite future, with all the standard extensions being implemented in this spec. 133 | 134 | [//]: # "## Example instructions" 135 | 136 | ## Documentation for model and tools 137 | 138 | ### snapshot of "Reading Guide", for those who just want to read it like an ISA manual 139 | 140 | RISC-V Spec Kami refers to "instruction databases" to model the behavior of the instructions that it supports. These database entries are referred to as "functional units" internally, and are stored in the following directories: FuncUnits/Alu/*.v, FuncUnits/Fpu/*.v, and FuncUnits/Mem/*.v. 141 | 142 | Each of these contains a datastructure that lists various RISC-V instructions. Each instruction entry has the following format: 143 | 144 | ``` 145 | {| 146 | instName = ... 147 | extensions = ... 148 | uniqId = ... 149 | inputXform = ... 150 | outputXform = ... 151 | optMemXform = ... 152 | instHints = ... 153 | |} 154 | ``` 155 | 156 | Every functional unit has a single "semantic function" which gives the basic operation performed by all of the affiliated instructions. For instance, the "add" functional unit supports several RISC-V instructions such as ADD, SUB, SLT (set less than), etc. This grouping of instructions into functional units enable generating optimized microarchitectures without having to reimplement the data-path functions. 157 | 158 | The `instName` field gives the instruction's name. The `extensions` field lists the RISC-V extensions that provide the instruction. The `uniqId` field, specifies the bit encoding that uniquely identifies the instruction. Finally `instHints` specifies the registers read or written by the instruction. 159 | 160 | The remaining three fields, `inputXform`, `outputXform`, and `optMemXform` are more complicated. 161 | 162 | `inputXform` specify how the values stored within various registers are transformed before being processed by the semantic function associated with the instruction's functional unit. `outputXform` specifies how the values returned by the semantic function are transformed before being written to various registers. And, `optMemXform` takes as input the output of the semantic function and the value returned by memory (for load/store/AMO instructions), and provide the value written to the register and to the memory. Note that of non memory instructions `optMemXform` is omitted. 163 | 164 | For example, Fpu.v contains the following entry for the `fnadd.s` instruction: 165 | 166 | ``` 167 | {| 168 | instName := "fadd.s"; 169 | extensions := ["RV32F"; "RV64F"]; 170 | uniqId 171 | := [ 172 | fieldVal instSizeField ('b"11"); 173 | fieldVal opcodeField ('b"10011"); 174 | fieldVal fmtField ('b"00"); 175 | fieldVal funct7Field ('b"0000000") 176 | ]; 177 | inputXform := add_in_pkt $0; 178 | outputXform := muladd_out_pkt; 179 | optMemXform := None; 180 | instHints := falseHints{*hasFrs1 := true*}{*hasFrs2 := true*}{*hasFrd := true*} 181 | |}; 182 | ``` 183 | 184 | Anyone may refer to these instruction database files to learn about the instructions defined within the RISC-V ISA. 185 | 186 | ### snapshot of "How to Compile/Run Guide" for those who want to execute a model on programs (ISA tests, Compliance tests, other programs) 187 | 188 | Our package includes two scripts for building and running our simulator program. 189 | 190 | To get all the submodules first, type `git submodule update --init`. 191 | 192 | To build the simulator from source simply run: `./doGenerate.sh`. See `./doGenerate.sh --help` for more information about building the program. 193 | 194 | To run RISC-V binaries within the simulator, simply run: `./runElf.sh $PATH/file.elf`, where `$PATH` represents the directory containing the RISC-V binary and `file.elf` represents the RISC-V binary. 195 | 196 | To run the suite of RISC-V binaries supported by the simulator, simply run: `./runTests.sh $PATH`, where `$PATH` represents the directory where the RISC-V binaries reside. The file `runTests.sh` lists all the binaries currently running on the simulator. 197 | 198 | In summary: 199 | ``` 200 | $ git submodule update --init 201 | $ ./doGenerate.sh 202 | $ ./runElf.sh $PATH/file.elf 203 | $ ./runTests.sh $PATH 204 | ``` 205 | 206 | ### snapshot of "How to Extend Guide" for those who want to extend the model to capture new ISA extensions/experiments. 207 | 208 | To add additional RISC-V instructions to our model, developers must add instruction entries to our instruction databases. 209 | 210 | The first step is to determine which functional unit to should be used to execute the new instruction. 211 | 212 | Every functional unit has an associated "semantic function". A semantic function is a generic function. For example, the "fcmp" functional unit has a semantic function that compares two floating point numbers. 213 | 214 | If none of the functional units can execute the new instruction, the developer needs to create a new functional unit entry. 215 | 216 | A function unit has the following format: 217 | 218 | ``` 219 | {| 220 | fuName := NAME; 221 | fuFunc := SEMANTICFUNCTION; 222 | fuInsts := [ ... ] 223 | |}. 224 | ``` 225 | 226 | `fuName` is a string that represents the functional unit's name. `fuFunc` is a Gallina function that represents the functional unit's semantic function. `fuInsts` is a list of instruction entries. 227 | 228 | Once the developer has selected, or created, the functional unit whose semantic function performs the given operation, they need to create an instruction entry. For example: 229 | 230 | ``` 231 | {| 232 | instName := "fadd.s"; 233 | extensions := ["RV32F"; "RV64F"]; 234 | uniqId 235 | := [ 236 | fieldVal instSizeField ('b"11"); 237 | fieldVal opcodeField ('b"10011"); 238 | fieldVal fmtField ('b"00"); 239 | fieldVal funct7Field ('b"0000000") 240 | ]; 241 | inputXform := add_in_pkt $0; 242 | outputXform := muladd_out_pkt; 243 | optMemXform := None; 244 | instHints := falseHints{*hasFrs1 := true*}{*hasFrs2 := true*}{*hasFrd := true*} 245 | |} 246 | ``` 247 | 248 | The developer will need to define the `inputXform`, `outputXform`, and `optMemXform` transformation functions. 249 | 250 | ## Compilation 251 | 252 | This package consists of a set of Kami files. The main processor model is written in Kami - a domain specific language embedded within Gallina. The Kami language constructs are defined in Kami. The model is defined in ProcKami. 253 | 254 | This model can be used to generate a processor simulator. The standard way to do this is to: 255 | 256 | 1. Compile the Kami/Coq files 257 | 2. "Extract" these files into Haskell 258 | 3. Compile the Haskell files to produce the Verilog code generator 259 | 4. Run the Verilog code generator to produce a Verilog processor model 260 | 5. Pass the Verilog model to Verilator to produce C source code for the processor simulator 261 | 6. Compile the C simulator. 262 | 263 | The `doGenerate.sh` script performs these steps when building the simulator. 264 | 265 | ## Bugs 266 | 267 | When the "RV64I" and "D" extensions are enabled, the current version of Verilator (4.012) generates calls to a function that does not exist - `VL_SHIFTR_QQW`. 268 | 269 | To fix this bug: 270 | 271 | 1. clone the latest version of Verilator using `git clone http://git.veripool.org/git/verilator` 272 | 2. add the following to include/verilated.h after the definition for `VL_SHIFTR_IIW`: 273 | ``` 274 | static inline QData VL_SHIFTR_QQW(int obits,int,int rbits,QData lhs, WDataInP rwp) VL_MT_SAFE { 275 | for (int i=1; i < VL_WORDS_I(rbits); ++i) { 276 | if (VL_UNLIKELY(rwp[i])) { // Huge shift 1>>32 or more 277 | return 0; 278 | } 279 | } 280 | return VL_CLEAN_QQ(obits,obits,lhs>>(static_cast(rwp[0]))); 281 | } 282 | ``` 283 | 3. compile Verilator using `./configure; make` 284 | 285 | A patched version of Verilator is available from Veripool. To download it simply execute `git clone http://git.veripool.org/git/verilator`. 286 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | The Public Review period was open: March 29, 2019 through May 13, 2019 2 | (standard 45 days recommended by the RISC-V Foundation). 3 | Following this, the RISC-V foundation selected the Sail model as its official formal specification. 4 | 5 | The following details are kept for reference, but more work has been done on some of the models since the review; the descriptions here may not be up to date. 6 | 7 | ---------------------------------------------------------------- 8 | # ISA Formal Spec Public Review 9 | 10 | To all who are interested in ISA Formal Specification for RISC-V, we (the ISA Formal Spec Technical Group in the RISC-V Foundation) invite your 11 | feedback on several draft Formal Specifications of the RISC-V ISA. We 12 | are interested in your opinions on how useful you would find each of 13 | the approaches represented here. 14 | To date, these have been developed by various subgroups, each for their own purposes and with their own priorities. 15 | 16 | This site contains (in addition to this README): 17 | 18 | - A summary of each of the approaches. The summaries are all written 19 | to a common template, for easier side-by-side comparison: 20 | 21 | - [GRIFT](GRIFT.md) (from Galois, Inc.) 22 | - [Forvis](Forvis.md) (from Bluespec, Inc.) 23 | - [Sail](Sail.md) (from the University of Cambridge, UK, and SRI International) 24 | - [riscv-plv](riscv-plv.md) (from MIT) 25 | - [Kami](Kami.md) (from SiFive) 26 | 27 | - A [comparison table](comparison_table.md) showing features in a tabular form. 28 | 29 | - The survey responses, both the individual responses (riscv-formal-isa-responses-all.pdf) 30 | and a summary (riscv-formal-isa-responses-summary.pdf). 31 | 32 | Each specification summary has a link to the project's home web site (all on GitHub) 33 | where you can explore that project's spec in full detail. Each 34 | project site, in addition to containing the spec itself, also has 35 | documentation on: 36 | 37 | - how to read the spec, even if you are 38 | unfamiliar with the host language in which the spec is written; 39 | 40 | - how to execute the spec (i.e., how to run 41 | RISC-V binaries using the spec as a simulator/emulator); 42 | 43 | - how to extend the spec (for future ISA extensions); 44 | 45 | - status and plans. 46 | 47 | ---------------------------------------------------------------- 48 | ## When and How to Provide Feedback, and What Happens Next 49 | 50 | The Public Review period is: March 29, 2019 through May 13, 2019 51 | (standard 45 days recommended by the RISC-V Foundation). 52 | 53 | There are two ways to provide feedback (please at least fill in the questionnaire): 54 | 55 | - A short, structured [questionnaire](https://docs.google.com/forms/d/e/1FAIpQLSe7jQx_IM2EqvHewuAKiROZXupwsqRu_pCgc-5d0y26DKph7A/viewform) 56 | (should not take more than a few minutes). 57 | 58 | - If you wish, you can provide more expansive free-form comments using the "Issues" tab of this GitHub repo. 59 | 60 | We are particularly interested in: 61 | 62 | - Your use cases: Are you likely to use the ISA Formal Spec? In what way? 63 | 64 | - Your general assessment of how each of the five approaches might meet your needs. 65 | 66 | At the end of the feedback period, the ISA Formal Spec Technical Group 67 | will respond to each issue raised, and will make a recommendation to 68 | the RISC-V Foundation about which of the five specs should be adopted 69 | as the "official" spec. 70 | 71 | An immediate use of the formal spec is to be the Golden Reference 72 | Model against which "Compliance" is measured by the RISC-V Foundation. 73 | 74 | Over time, the spec is expected to be maintained and to grow to 75 | include future official features/extensions of the RISC-V ISA. 76 | 77 | 78 | ------------------------------------------------------------- 79 | ## Scope 80 | 81 | The initial target for the group is the following set of features only: 82 | 83 | - RV32 and RV64 84 | 85 | - Base instruction set (I), Integer Multiply Divide (M), Atomics (A), 86 | Single- and Double-precision floating point (F, D), Compressed 87 | instructions (C). 88 | 89 | - Privilege modes M (machine), S (Supervisor) and U (User), including 90 | Sv32, Sv39 and Sv48 virtual memory schemes; traps and interrupts; 91 | Zicsr (CSRs); Zifencei. 92 | 93 | - Interaction with the RISC-V Memory Model. 94 | 95 | The spec is expected to be extensible in the future to cover other 96 | standard ISA features that are still in development within the RISC-V 97 | Foundation (e.g., Vector, Bit Manipulation, Crypto, J, SIMD, ...). 98 | The specs are all open-source, so they may also be extended by others 99 | for their own custom ISA extensions (some activities like this are 100 | already in progress). 101 | 102 | All the five models here are works in progress, and so may not be 103 | ready with all the above features. Each project's Summary page and 104 | home site describes status and plans for the future. 105 | 106 | ---------------------------------------------------------------- 107 | ## Background on "What is a Formal Spec? Why Have One?" 108 | 109 | A RISC-V ISA Formal Spec is a purely functional, precise and formal, 110 | simple specification of the ISA. 111 | 112 | "Purely functional" means that it just describes the functional 113 | semantics of instructions, and does not try to capture implementation 114 | properties such as performance, area, power, etc. As such, it plays a 115 | similar role as the text specification of the ISA, as well as a purely 116 | functional simulator for RISC-V binaries. 117 | 118 | "Precise and formal" means that it is written in a formal language 119 | which itself has clear semantics; that it is executable, and that it 120 | is machine readable for manipulation by formal tools. Of course, it 121 | should be precise, complete, and unambiguous. (This is where it 122 | differs from a text spec and most production simulators.) 123 | 124 | "Simple" means it should be understandable and usable by a wide 125 | audience---not just experts in formal methods, but also assembly 126 | language programmers, compiler writers, and hardware designers, many 127 | of whom may not have a background in formal methods and may not have 128 | the interest or time to acquire one. 129 | 130 | When finalized, the RISC-V ISA Formal Spec is expected to become *the* 131 | definitive authority on semantics of RISC-V instructions. It will be 132 | also be used in official Compliance Testing to certify compliance. 133 | 134 | ### Choice of language in which a formal spec is written 135 | 136 | Raw execution speed of the formal spec when used as a 137 | simulator/emulator is desirable, but is secondary to the requirements 138 | listed above. Nevertheless, for some use cases (such as tandem 139 | verification) execution speed needs to be good enough to execute 140 | non-trivial programs (such as booting an OS and running apps under the 141 | OS). 142 | 143 | The five approaches each chose their host language for these reasons. 144 | It is very rare to choose, for a formal spec, a large and complex 145 | language that is difficult for formal reasoning (such as C++), or to 146 | write it in a style that favors speed over simplicity and clarity. 147 | 148 | Note, some of the five formal specs here use the C++ Berkeley 149 | "softfloat" library to implement IEEE floating point. This should not 150 | be seen as part of the formal spec, but just as a temporary 151 | placeholder to enable full-system simulation/emulation. Each 152 | project's documentation may describe future plans for this. 153 | 154 | ---------------------------------------------------------------- 155 | -------------------------------------------------------------------------------- /Sail.md: -------------------------------------------------------------------------------- 1 | # RISC-V ISA Formal Specification: Sail Model 2 | 3 | ## Name 4 | 5 | Sail RISC-V model 6 | 7 | ## Authors (with institutions) 8 | 9 | Prashanth Mundkur, SRI International; 10 | Rishiyur Nikhil (Bluespec Inc.); 11 | Jon French, University of Cambridge; 12 | Brian Campbell, University of Edinburgh; 13 | Robert Norton, University of Cambridge; 14 | Alasdair Armstrong, University of Cambridge; 15 | Thomas Bauereiss, University of Cambridge; 16 | Shaked Flur, University of Cambridge; 17 | Peter Sewell, University of Cambridge 18 | 19 | 20 | ## Spec sources snapshot (e.g. URL to github repo) 21 | 22 | ## Spec sources live development (e.g. URL to github repo) 23 | 24 | 25 | 26 | 27 | ## Licence 28 | 29 | BSD two-clause 30 | 31 | 32 | ## Metalanguage (including brief explanation of the metalanguage used) 33 | 34 | This ISA specification is written in [Sail](https://www.cl.cam.ac.uk/~pes20/sail/). 35 | 36 | Sail is a language for describing the instruction-set architecture 37 | (ISA) semantics of processors, in an engineer-friendly, 38 | vendor-pseudocode-like style. Sail is essentially a first-order 39 | imperative language, but with lightweight dependent types 40 | (automatically checked using Z3) for the bitvector lengths and integer 41 | ranges that are pervasive in ISA specifications. Given a Sail 42 | definition, the tool will type-check it and generate executable 43 | emulators, in C and OCaml, theorem-prover definitions for Isabelle, 44 | HOL4, and Coq, and definitions to integrate with our 45 | [RMEM](http://www.cl.cam.ac.uk/users/pes20/rmem) 46 | and [isla-axiomatic](https://isla-axiomatic.cl.cam.ac.uk/) tools for concurrency 47 | semantics. 48 | 49 | ![Sail overview](http://www.cl.cam.ac.uk/users/pes20/sail/overview-sail.png) 50 | 51 | ## Dependencies on what tools 52 | 53 | Sail is available as pre-built binaries via OPAM, as a source package, and as source in a github repository, BSD licenced. 54 | It depends on OCaml, OPAM, libgmp-dev, Z3, Lem, and Ott. 55 | 56 | 57 | ## Tool ecosystem: what other work has been/is being done with those tools 58 | 59 | 60 | Sail is being used for multiple ISA descriptions, including 61 | essentially complete versions of the sequential behaviour of ARMv8-A 62 | (automatically derived from the authoritative ARM-internal 63 | specification, and released under a BSD Clear licence with ARM's 64 | permission), RISC-V, MIPS, and CHERI-MIPS; all these are complete 65 | enough to boot various operating systems. There are also Sail models 66 | for smaller fragments of IBM POWER and x86. 67 | 68 | Sail is being used: 69 | 70 | - as an ISA design tool for CHERI, both as an executable reference model and for the pseudocode in the CHERI ISA manual 71 | - to make theorem-prover ISA definitions available, for multiple architectures and targetting multiple theorem provers 72 | - to support work on architecture concurrency models 73 | 74 | 75 | ## Motivation (a few sentences explaining for what the authors have developed this spec) 76 | 77 | The Sail RISC-V ISA model has been developed: 78 | 79 | - as a basis for the design of a CHERI variant of RISC-V, incorporating hardware support for fine-grain memory protection and secure encapsulation. 80 | - to support our work on the RISC-V concurrency architecture, providing the ISA semantics required by our [RMEM](http://www.cl.cam.ac.uk/users/pes20/rmem) tool for concurrency 81 | semantics, which lets one compute all the concurrency-model-allowed behaviours of small litmus tests or ELF binaries. 82 | - to provide theorem-prover definitions of the RISC-V ISA, for multiple provers 83 | - to support the automatic generation of instruction tests 84 | - to use as a test oracle in tandem verification 85 | - to provide readable pseudocode that could be used in the RISC-V ISA specification 86 | 87 | ## Current functional coverage (what's modelled now, in RISC-V code and in English) 88 | 89 | - The model covers RV32 and RV64 IMAFDC (base 32-bit and 64-bit integer architectures, with the standard 90 | multiply/divide, atomic, and compressed extensions), M/S/U (machine, 91 | supervisor and user privilege) modes, and the Sv32, Sv39, and Sv48 modes 92 | of address translation. Operation in M-only, M/U and M/S/U 93 | modes are all supported. The model includes a specification for the 94 | draft 'N' extension for user-level interrupt handling. 95 | 96 | - The model supports parameterization for platform-specific implementation choices. 97 | 98 | - The model has extendability hooks that are being used to develop the 99 | CHERI-RISC-V architecture. 100 | 101 | - The model does not currently cover RV128, the hypervisor mode for virtualization, 102 | and other extensions such as the vector and bit-manipulation extensions. 103 | 104 | ## Current specification of assembly syntax and encoding 105 | 106 | The model includes an executable specification of the assembly 107 | language encoder/decoder. 108 | 109 | ## Current treatment of concurrency 110 | 111 | The ISA model is integrated with the operational model of the RISC-V 112 | relaxed memory model, RVWMO (as described in an appendix of the [RISC-V 113 | user-level specification](https://github.com/riscv/riscv-isa-manual/releases/tag/draft-20181227-c6741cb)), which is one of the reference models used 114 | in the development of the RISC-V concurrency architecture; this is 115 | part of our [RMEM](http://www.cl.cam.ac.uk/users/pes20/rmem) tool. 116 | It is also integrated with the RISC-V axiomatic concurrency model 117 | as part of our [isla-axiomatic](https://isla-axiomatic.cl.cam.ac.uk/) tool. 118 | 119 | 120 | ## Current treatment of floating-point 121 | 122 | The Sail RISC-V model supports floating point for the generated C emulator, using the Softfloat library; it does not currently support floating point for the theorem-prover targets. 123 | 124 | ## Current capabilities (what the specification and associated tooling generates and enables) 125 | 126 | ### Emulation 127 | 128 | The model provides OCaml and C emulators that can execute RISC-V ELF 129 | files, and both emulators provide platform support sufficient to boot 130 | Linux, FreeBSD and seL4. The OCaml emulator can generate its own 131 | platform device-tree description, while the C emulator currently 132 | requires a consistent description to be manually provided. The C 133 | emulator can be linked against the Spike emulator for execution with 134 | per-instruction tandem-verification. 135 | 136 | The C emulator, for the Linux boot, currently runs at approximately 137 | 300 KIPS on an Intel i7-7700 (when detailed per-instruction tracing 138 | is disabled), and there are many opportunities for future optimisation 139 | (our Sail MIPS model runs at approximately 1 MIPS). This enables us to 140 | boot Linux in about 4 minutes, and FreeBSD in about 2 minutes. Memory 141 | usage for the C emulator when booting Linux is approximately 140MB. 142 | 143 | 144 | ### Use as test oracle in tandem verification 145 | 146 | For tandem verification of random instruction streams we support the 147 | protocols used in [TestRIG](https://github.com/CTSRD-CHERI/TestRIG) to 148 | directly inject instructions into the C emulator and produce trace 149 | information in RVFI format. This has been used for cross testing 150 | against spike and the [RVBS](https://github.com/CTSRD-CHERI/RVBS) 151 | specification written in Bluespec SystemVerilog. 152 | 153 | The C emulator can also be directly linked to Spike, which provides 154 | tandem-verification on ELF binaries (including OS boots). This is 155 | often useful in debugging OS boot issues in the model when the boot is 156 | known working on Spike. It is also useful to detect platform-specific 157 | implementation choices in Spike that are not mandated by the ISA 158 | specification. 159 | 160 | ### Theorem-prover definitions that support proof 161 | 162 | With Sail we aim to support the generation of idiomatic theorem prover 163 | definitions across multiple tools. At present we support Isabelle, 164 | HOL4 and Coq, and provide snapshots of the generated theorem prover 165 | definitions. Typically the verification community has been split 166 | across tool-specific lines, for example in verified compilation the 167 | CakeML project uses HOL4, seL4 uses Isabelle, and CompCert and CertiKOS use Coq. Given the broad 168 | interest in formal ISA specs among this community and others, we 169 | consider the ability to target multiple tools to be of key practical 170 | importance. 171 | 172 | For the Sail RISC-V model, we currently generate definitions in HOL4, 173 | Isabelle, and Coq that are accepted by each of those tools. We have tested 174 | HOL4 Kananaskis-12, Isabelle 2018, and Coq 8.8.1. 175 | 176 | For Coq, we generate definitions that preserve most of the 177 | liquid/dependent typing from the Sail specification, whereas for 178 | Isabelle and HOL4 we perform a specialised partial monomorphisation 179 | that retains useful typing information where possible yet avoids 180 | duplicating code unnecessarily. 181 | 182 | Our theorem-prover translation can target multiple monads for 183 | different purposes. The first is a state monad with nondeterminism and 184 | exceptions, suitable for reasoning in a sequential setting, assuming 185 | that effectful expressions are executed without interruptions and with 186 | exclusive access to the state. 187 | 188 | For reasoning about concurrency, where instructions execute 189 | out-of-order, speculatively, and non-atomically, we provide a free 190 | monad over an effect datatype of memory actions. This monad is also 191 | used as part of our aforementioned concurrency support via the RMEM 192 | tool. 193 | 194 | ### Use in documentation 195 | 196 | Latex definitions can be generated from the model that are suitable 197 | for inclusion in reference documentation. Drafts of the RISC-V 198 | [unprivileged](https://github.com/rems-project/riscv-isa-manual/blob/sail/release/riscv-spec-sail-draft-alpha2.pdf) 199 | and 200 | [privileged](https://github.com/rems-project/riscv-isa-manual/blob/sail/release/riscv-privileged-sail-draft-alpha2.pdf) 201 | specifications that include the Sail formal definitions are available 202 | in the sail branch of this [riscv-isa-manual 203 | repository](https://github.com/rems-project/riscv-isa-manual/tree/sail). 204 | 205 | ### Use in test generation 206 | 207 | Our OCaml backend can produce QuickCheck-style random generators for 208 | types in Sail specifications, which we have used to produce random 209 | instructions sequences for testing. The generation of individual 210 | types can be overridden by the developer to, for example, remove 211 | implementation-specific instructions or introduce register biasing. 212 | 213 | Measuring line and branch coverage of the C emulator generated from 214 | the Sail specification, the RISC-V test suite (not the new compliance 215 | suite, because it will need some setup and is mostly RV32) hits 73% 216 | (line) / 64% (branch), while the Sail-generated random tests cover 49% 217 | / 30%. This lower coverage is not a surprise: the latter currently 218 | does not generate CSR or AMO related instructions, so is presumably 219 | not hitting the memory and interrupt handling code used by these. 220 | 221 | ### Use for concurrency-model litmus test evaluation 222 | 223 | As part of our concurrency architecture work, we have produced and 224 | released a library of approximately 7000 [litmus 225 | tests](https://github.com/litmus-tests/litmus-tests-riscv). The 226 | operational and axiomatic RISC-V concurrency models are in sync for 227 | these tests, and they moreover agree with the corresponding ARM 228 | architected behaviour for the tests in common. 229 | 230 | We have also run these tests on RISC-V hardware, on a SiFive RISC-V 231 | FU540 multicore proto board (Freedom Unleashed), kindly on loan from 232 | Imperas. To date, we see only sequentially consistent behaviour there. 233 | 234 | 235 | ## Current test coverage 236 | 237 | ### Basic (riscv-tests) tests 238 | 239 | Yes 240 | 241 | ### RISC-V compliance tests 242 | 243 | Both the C and OCaml emulators support use as a test target in the 244 | compliance-test framework, and we intend to support use as a golden model. 245 | 246 | ### OS boot testing 247 | 248 | The 64-bit C and OCaml emulators have been used to boot Linux and FreeBSD 249 | up to the login prompt, including most of the standard startup scripts 250 | and programs, and the seL4 kernel running its test suite. 251 | OS boots for the 32-bit emulators are in progress. 252 | 253 | 254 | ### Concurrency litmus test testing 255 | 256 | The model supports all the litmus tests mentioned above, which are the 257 | only concurrency test collection for RISC-V that we are aware of. 258 | 259 | ### Other 260 | 261 | 262 | ## Plans for future functional coverage 263 | 264 | We plan to add support for the F and D standard 265 | floating-point extensions, support for HINT encodings, PMP/PMA physical memory attributes 266 | and protection. 267 | This may be followed by support for the hypervisor mode. 268 | 269 | ## Plans for long-term access, maintenance, etc. 270 | 271 | Sail is an academic project, developed from 2014 to date. It is a 272 | central part of our research infrastructure, so we expect to actively 273 | maintain it for the foreseeable future. It is open-source, BSD 274 | licenced, and developed in a public github repository. 275 | 276 | The Sail RISC-V model is necessary for our research on CHERI; it is 277 | also one of the several ISA models that we aim to continue to make 278 | available in multiple theorem-prover targets, to support software and 279 | hardware verification. We thus also expect to maintain it for the 280 | foreseeable future. We may not have the resources or motivation to 281 | ourselves define every RISC-V extension in Sail, but that is properly 282 | the task of extension authors, and we would be happy to support them 283 | to do so. 284 | 285 | 286 | 287 | 288 | ## Example instructions 289 | 290 | These are verbatim excerpts from the main model file, [riscv.sail](https://github.com/rems-project/sail-riscv/blob/master/model/riscv.sail), with a few comments added. 291 | 292 | ### ITYPE (or ADDI) 293 | ~~~~~ 294 | /* the assembly abstract syntax tree (AST) clause for the ITYPE instructions */ 295 | 296 | union clause ast = ITYPE : (bits(12), regbits, regbits, iop) 297 | 298 | /* the encode/decode mapping between AST elements and 32-bit words */ 299 | 300 | mapping encdec_iop : iop <-> bits(3) = { 301 | RISCV_ADDI <-> 0b000, 302 | RISCV_SLTI <-> 0b010, 303 | RISCV_SLTIU <-> 0b011, 304 | RISCV_ANDI <-> 0b111, 305 | RISCV_ORI <-> 0b110, 306 | RISCV_XORI <-> 0b100 307 | } 308 | 309 | mapping clause encdec = ITYPE(imm, rs1, rd, op) <-> imm @ rs1 @ encdec_iop(op) @ rd @ 0b0010011 310 | 311 | /* the execution semantics for the ITYPE instructions */ 312 | 313 | function clause execute (ITYPE (imm, rs1, rd, op)) = { 314 | let rs1_val = X(rs1); 315 | let immext : xlenbits = EXTS(imm); 316 | let result : xlenbits = match op { 317 | RISCV_ADDI => rs1_val + immext, 318 | RISCV_SLTI => EXTZ(rs1_val <_s immext), 319 | RISCV_SLTIU => EXTZ(rs1_val <_u immext), 320 | RISCV_ANDI => rs1_val & immext, 321 | RISCV_ORI => rs1_val | immext, 322 | RISCV_XORI => rs1_val ^ immext 323 | }; 324 | X(rd) = result; 325 | true 326 | } 327 | 328 | /* the assembly/disassembly mapping between AST elements and strings */ 329 | 330 | mapping itype_mnemonic : iop <-> string = { 331 | RISCV_ADDI <-> "addi", 332 | RISCV_SLTI <-> "slti", 333 | RISCV_SLTIU <-> "sltiu", 334 | RISCV_XORI <-> "xori", 335 | RISCV_ORI <-> "ori", 336 | RISCV_ANDI <-> "andi" 337 | } 338 | 339 | mapping clause assembly = ITYPE(imm, rs1, rd, op) 340 | <-> itype_mnemonic(op) ^ spc() ^ reg_name(rd) ^ sep() ^ reg_name(rs1) ^ sep() ^ hex_bits_12(imm) 341 | ~~~~~~ 342 | 343 | ### SRET 344 | 345 | ~~~~~ 346 | union clause ast = SRET : unit 347 | 348 | mapping clause encdec = SRET() <-> 0b0001000 @ 0b00010 @ 0b00000 @ 0b000 @ 0b00000 @ 0b1110011 349 | 350 | function clause execute SRET() = { 351 | match cur_privilege { 352 | User => handle_illegal(), 353 | Supervisor => if mstatus.TSR() == true 354 | then handle_illegal() 355 | else nextPC = handle_exception(cur_privilege, CTL_SRET(), PC), 356 | Machine => nextPC = handle_exception(cur_privilege, CTL_SRET(), PC) 357 | }; 358 | false 359 | } 360 | 361 | mapping clause assembly = SRET() <-> "sret" 362 | ~~~~~ 363 | 364 | ## Documentation for model and tools 365 | 366 | There is a [manual for Sail](https://github.com/rems-project/sail/blob/sail2/manual.pdf), 367 | which describes the features of the language, provides information 368 | about the various command-line flags and targets, and contains a small 369 | tutorial for ISA description in Sail based on a two-instruction 370 | fragment of RISC-V. 371 | 372 | ### snapshot of "Reading Guide", for those who just want to read it like an ISA manual 373 | 374 | There are two options for a reading guide. If one intends to 375 | understand some detail of the ISA specification documents, one could 376 | use the Sail-annotated of the RISC-V architecture specifications available in the sail branch of 377 | : 378 | the [unprivileged](https://github.com/rems-project/riscv-isa-manual/blob/sail/release/riscv-spec-sail-draft-alpha2.pdf) 379 | and 380 | [privileged](https://github.com/rems-project/riscv-isa-manual/blob/sail/release/riscv-privileged-sail-draft-alpha2.pdf) specs. 381 | If one intends to understand the Sail model itself, one could use the 382 | [ReadingGuide](https://github.com/rems-project/sail-riscv/blob/master/doc/ReadingGuide.md) provided in the model repository. 383 | 384 | ### snapshot of "How to Compile/Run Guide" for those who want to execute a model on programs (ISA tests, Compliance tests, other programs) 385 | 386 | The documentation in the model repository provides basic instructions 387 | to compile and run the C and OCaml emulators on ELF files and OS binaries. 388 | 389 | ### snapshot of "How to Extend Guide" for those who want to extend the model to capture new ISA extensions/experiments. 390 | 391 | A [guide](https://github.com/rems-project/sail-riscv/blob/master/doc/ExtendingGuide.md) 392 | to extending the model is provided in the repository. 393 | 394 | 395 | 396 | ## Caveats and limitations (anything potential users should be aware of that is not clear above) 397 | 398 | none 399 | -------------------------------------------------------------------------------- /comparison_table.md: -------------------------------------------------------------------------------- 1 | This is a table of the easily summarisable aspects of the RISC-V Formal ISA model comparison. It should be read together with the linked-to descriptions for each model. This table describes the current state of the models only, not work in progress and future plans; see the descriptions for those. 2 | 3 | | | Forvis | Grift | Sail | riscv-plv | Kami | 4 | | ------------------------------------------------- | ------------- | ------------------------------ | ------------------------| ------------------- | ---------- | 5 | | Link to description | [Forvis](https://github.com/riscv/ISA_Formal_Spec_Public_Review/blob/master/Forvis.md) | [Grift](https://github.com/riscv/ISA_Formal_Spec_Public_Review/blob/master/GRIFT.md) | [Sail](https://github.com/riscv/ISA_Formal_Spec_Public_Review/blob/master/Sail.md) | [Riscv-plv](https://github.com/riscv/ISA_Formal_Spec_Public_Review/blob/master/riscv-plv.md) | [Kami](https://github.com/sifive/RiscvSpecFormal) | 6 | | Author/Group | Bluespec |Galois |SRI/Cambridge | MIT | SiFive | 7 | | Licence | MIT |GPL3 |BSD | MIT | Apache 2.0 | 8 | | Metalanguage | Haskell |Haskell |Sail | Haskell | Kami/Coq | 9 | | Functional coverage - Base ISA and extensions | RV32/64IMAFDC |RV32/64GC |RV32/RV64IMAFDC | RV32/64IMAF | RV32/64GC | 10 | | Functional coverage - Privilege levels | MUS,Sv32,39,48|M |MUS,Sv32,39,48 | Sv39 | MUS,Sv32,39,48| 11 | | Specification of assembly syntax and encoding | no |pp |yes | no | yes | 12 | | Concurrency | no |no |yes | no | yes | 13 | | Floating-point | via Softfloat |via Softfloat |via Softfloat | via Softfloat | Native implementation of IEEE 754-2008 | 14 | | Simulation/Emulation | Haskell | Haskell |generated C or OCaml | Haskell | Verilator | 15 | | ...emulation speed | 75K IPS (180M instrs/40min Linux boot) |40K IPS on Intel Xeon E312 |300K IPS on Intel i7-7700 (4min Linux boot) | 100K IPS on 6700HQ (Linux boot) | Not measured | 16 | | Use as test oracle in tandem verification | yes |no |yes | yes | yes | 17 | | Theorem-prover definitions | via hs-to-coq |no |Coq,Isa,HOL4 | hs-to-coq | Coq | 18 | | Use in documentation | to LaTeX |to text |to LaTeX in RISC-V ISA | no | no | 19 | | Use in test generation | no |no |yes | no | no | 20 | | Use for concurrency-model litmus test evaluation | no |no |yes | no | no | 21 | | Test coverage - riscv-tests suite | all |yes |yes | yes | yes | 22 | | Test coverage - RISC-V compliance tests | yes |almost all |yes | yes | yes | 23 | | Test coverage - OS boots | Linux,FreeRTOS|no |Linux,FreeBSD,seL4 | Linux | no | 24 | | Test coverage - Concurrency litmus tests | no |no |yes | no | no | 25 | 26 | -------------------------------------------------------------------------------- /riscv-formal-isa-responses-all.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/riscvarchive/ISA_Formal_Spec_Public_Review/d42ce01319043a18c50e7f07cbf97fd0d264ced3/riscv-formal-isa-responses-all.pdf -------------------------------------------------------------------------------- /riscv-formal-isa-responses-summary.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/riscvarchive/ISA_Formal_Spec_Public_Review/d42ce01319043a18c50e7f07cbf97fd0d264ced3/riscv-formal-isa-responses-summary.pdf -------------------------------------------------------------------------------- /riscv-plv.md: -------------------------------------------------------------------------------- 1 | # RISC-V ISA Formal Specification 2 | 3 | ## Name (e.g. Sail Model) 4 | 5 | riscv-plv 6 | 7 | ---------------------------------------------------------------- 8 | ## Authors (with institutions) 9 | 10 | Ian J Clester, Thomas Bourgeat, Andy Wright, Samuel Gruetter, Adam Chlipala (MIT) 11 | 12 | ---------------------------------------------------------------- 13 | ## Spec sources snapshot (e.g. URL to github repo) 14 | 15 | https://github.com/mit-plv/riscv-semantics 16 | 17 | ---------------------------------------------------------------- 18 | ## Spec sources live development (e.g. URL to github repo) 19 | 20 | In various branches of 21 | 22 | https://github.com/mit-plv/riscv-semantics 23 | 24 | ---------------------------------------------------------------- 25 | ## Licence 26 | 27 | MIT (Requires update to the files to state it properly, but everyone agreed) 28 | 29 | ---------------------------------------------------------------- 30 | ## Metalanguage (including brief explanation of the metalanguage used) 31 | 32 | Haskell, a functional programming language that is used widely and well-supported (at least by the standards of functional languages!). 33 | We make an effort to restrict ourselves to a small subset of Haskell features, to ease the construction of tools to translate from our code to other formats automatically. 34 | However, we retain the advantage of an easy path to running the semantics as an interpreter, via the normal Haskell compiler. 35 | 36 | ---------------------------------------------------------------- 37 | ## Dependencies on what tools 38 | 39 | Haskell, SoftFloat. We pull Haskell dependencies using Stack (a Haskell package manager). 40 | 41 | ---------------------------------------------------------------- 42 | ## Tool ecosystem: what other work has been/is being done with those tools 43 | 44 | We have made an effort to separate the core specification from "platforms" that can be plugged in to run it in different modes. 45 | Here are some of our uses so far. 46 | - Normal simulation `(rv[32|64]i(m)(a)(f))` with or without IO devices (buffered or not) 47 | - Tandem verification (in a branch), meaning we can run another ISA simulator or a hardware processor simulator in parallel to our semantics, catching where they diverge 48 | - `rv32i` (without any CSRs) compiled as a circuit and model-checked against Clifford Wolf's `rv-formal` (and therefore, transitively, against Spike) 49 | 50 | The spec is also transliterated to Coq ([`riscv-coq`](https://github.com/samuelgruetter/riscv-coq)) using [`hs-to-coq`](https://github.com/antalsz/hs-to-coq) and 51 | used to interface with proof of processors ([Kami](https://github.com/mit-plv/kami)) and with proof of compilers. 52 | 53 | 54 | ---------------------------------------------------------------- 55 | ## Motivation (a few sentences explaining for what the authors have developed this spec) 56 | 57 | We wanted a unified way to interact with the different projects 58 | of our group involving RISC-V: proving software in 59 | Coq, proving simple hardware in Coq (Kami), developing 60 | architectures in Bluespec. Our goal is for the same semantics to be 61 | palatable to partisans of all formal-methods tools (so no bias 62 | towards any one of them) and to practitioners (so no assumption of 63 | background in functional programming or formal methods). 64 | 65 | ---------------------------------------------------------------- 66 | ## Current functional coverage (what's modelled now, in RISC-V code and in English) 67 | 68 | ### Base ISA and extensions 69 | 70 | `i,m,f,a` 71 | 72 | ### Privilege levels 73 | 74 | `M,S,U` with more or less testing. 75 | No user-level exceptions. 76 | 77 | ---------------------------------------------------------------- 78 | ## Current specification of assembly syntax and encoding 79 | 80 | We use normal GCC and load ELF files. 81 | The instructions are represented in an algebraic data type defined in `src/Spec/Decode.hs`. 82 | Here's one example instruction: 83 | Lb { rd :: Register, rs1 :: Register, oimm12 :: MachineInt } 84 | The same source file contains a decoder from the binary format to syntax trees. 85 | 86 | ---------------------------------------------------------------- 87 | ## Current treatment of concurrency 88 | 89 | We have designed our semantics to be "pluggable" into different concurrency models. 90 | Basically, we aim to provide a kind of oracle about how a single thread behaves, 91 | parameterized over a platform making such decisions as results of memory operations. 92 | We have made some very preliminary experiments with a simple platform that could 93 | connect to weak memory models, but this potential use of the semantics is not 94 | yet fleshed out. Another work in progress is examining how to model 95 | memory-mapped IO, but this effort also doesn't have firm conclusions yet. 96 | 97 | ---------------------------------------------------------------- 98 | ## Current treatment of floating-point 99 | 100 | We piggyback on the SoftFloat library to support the `f` extension. 101 | 102 | ---------------------------------------------------------------- 103 | ## Current capabilities (what the specification and associated tooling generates and enables) 104 | 105 | ### Emulation 106 | 107 | Our naive purely functional platform implementation goes at ~100k instructions per second. 108 | We are experimenting with various optimizations, which so far have improved performance by a factor of two. 109 | The modular nature of the semantics allows others to experiment with new platforms without touching the core specification. 110 | 111 | ### Use as test oracle in tandem verification 112 | 113 | We have tandem verification running to compare our semantics against Spike booting Linux. 114 | Again, it requires an alternative platform implementation and depends on no special support in the core semantics. 115 | 116 | ### Theorem-prover definitions that support proof 117 | 118 | [`riscv-coq`](https://github.com/samuelgruetter/riscv-coq) is used as the target semantics of a verified compiler (ongoing work) and for 119 | the export target of Kami (hardware) semantics. 120 | 121 | ### Use in documentation 122 | 123 | We don't do any automatic documentation generation yet, but it has been among our planned backends. 124 | 125 | ### Use in test generation 126 | 127 | None yet, but it seems clear how to write an alternative platform implementation to do some sort of random and/or smart-coverage test generation. 128 | 129 | ### Use for concurrency-model litmus test evaluation 130 | 131 | None yet 132 | 133 | ---------------------------------------------------------------- 134 | ## Current test coverage 135 | 136 | ### RISC-V compliance tests 137 | 138 | `rv32im` + `riscv-test` 139 | 140 | ### OS boot testing 141 | 142 | Our emulator currently boots Linux, though it requires a PLIC and a CLINT which 143 | are both in the misnamed branch FastIO. 144 | 145 | ### Concurrency litmus test testing 146 | 147 | None 148 | 149 | ### Other 150 | 151 | We emphasized as much as possible the distinction between 152 | *platform* and *spec*. For example, whether a dirty bit is set in hardware 153 | or software is left to the platform, so our spec expects 154 | a helper from the platform to tell it what choice to make. 155 | Another example is the way the WARL fields are handled. 156 | All this is unspecified in the spec, which calls a handler 157 | that needs to be defined by the platform. 158 | 159 | 160 | ---------------------------------------------------------------- 161 | ## Plans for future functional coverage 162 | 163 | Interaction with the weak memory model by implementing a monad following the operational 164 | semantics for loadW,storeW. 165 | 166 | ---------------------------------------------------------------- 167 | ## Plans for long-term access, maintenance, etc. 168 | 169 | There's no reason to try to hide that this is an academic project at the moment! 170 | It is hard to predict the precise maintenance trajectory of the semantics or associated tools, 171 | though it would be nice to see the RISC-V Foundation adopt some semantics as blessed 172 | open-source projects, with contributors from various member companies. 173 | However, by building on Haskell, a widely used language with serious maintainers, we at 174 | least avoid being on the hook for a toolset sufficient to run our semantics as an emulator. 175 | 176 | ---------------------------------------------------------------- 177 | ## Example instructions 178 | 179 | ### ITYPE (or ADDI) 180 | 181 | ``` 182 | execute (Addi rd rs1 imm12) = do 183 | x <- getRegister rs1 184 | setRegister rd (x + fromImm imm12) 185 | ``` 186 | 187 | ### SRET 188 | 189 | ``` 190 | 191 | execute Sret = do 192 | priv <- getPrivMode 193 | when (priv < Supervisor) (raiseException 0 2) 194 | tsr <- getCSRField Field.TSR 195 | when (tsr == 1 && priv == Supervisor) (raiseException 0 2) 196 | spp <- getCSRField Field.SPP 197 | setCSRField Field.SPP (encodePrivMode User) 198 | setPrivMode (decodePrivMode spp) 199 | spie <- getCSRField Field.SPIE 200 | setCSRField Field.SPIE 1 201 | setCSRField Field.SIE spie 202 | sepc <- getCSRField Field.SEPC 203 | setPC ((fromIntegral:: MachineInt -> t) sepc) 204 | 205 | ``` 206 | 207 | ---------------------------------------------------------------- 208 | ## Documentation for model and tools 209 | 210 | ### snapshot of "Reading Guide", for those who just want to read it like an ISA manual 211 | 212 | It's in `READING.md` at the top level of the repo. 213 | 214 | ### snapshot of "How to Compile/Run Guide" for those who want to execute a model on programs (ISA tests, Compliance tests, other programs) 215 | 216 | It's in `README.md` at the top level of the repo. 217 | 218 | ### snapshot of "How to Extend Guide" for those who want to extend the model to capture new ISA extensions/experiments. 219 | 220 | Sorry, we haven't written one yet. 221 | --------------------------------------------------------------------------------