{"id":18304464,"url":"https://github.com/spinalhdl/rvls","last_synced_at":"2025-04-05T15:31:18.541Z","repository":{"id":185275780,"uuid":"673241598","full_name":"SpinalHDL/rvls","owner":"SpinalHDL","description":"RISCV lock-step checker based on Spike","archived":false,"fork":false,"pushed_at":"2024-02-05T13:09:45.000Z","size":174,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-02-28T05:39:38.858Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SpinalHDL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSES/CC0-1.0.txt","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}},"created_at":"2023-08-01T07:32:23.000Z","updated_at":"2024-04-15T11:33:37.505Z","dependencies_parsed_at":"2023-12-02T10:24:36.144Z","dependency_job_id":"3e2cd50a-35b7-4ce5-85e4-845218c4829c","html_url":"https://github.com/SpinalHDL/rvls","commit_stats":null,"previous_names":["spinalhdl/rvls"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpinalHDL%2Frvls","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpinalHDL%2Frvls/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpinalHDL%2Frvls/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpinalHDL%2Frvls/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SpinalHDL","download_url":"https://codeload.github.com/SpinalHDL/rvls/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247358614,"owners_count":20926260,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T15:29:00.861Z","updated_at":"2025-04-05T15:31:16.390Z","avatar_url":"https://github.com/SpinalHDL.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction\n\nRVLS (Risc-V Lock Step) is a CPU simulation trace checker.\n- Typical usage is to check that a simulated CPU system is behaving right\n- Has a human-readable text frontend to feed the traces\n- Can be directly integrated into a C++ sim for direct checking\n- Has a Java JNI frontend for its integration in a SpinalHDL / Chisel based testbench\n- Support multi-core systems, by tracking memory coherency status across CPUs\n- Use Spike's \"proc\" as golden reference model\n- Use a lightly modified Spike version to provide more info and allow coherency checks\n\nSee [example/simple/trace.log](example/simple/trace.log) for an example of ASCII trace which can be checked by RVLS\n\nRVLS is used to check the behaviour of multicore NaxRiscv. \nNaxRiscv use a Write-Back L1 data cache, with tilelink to provide memory coherency between the cores, using a MESI protocol (https://en.wikipedia.org/wiki/MESI_protocol)\n\nNot everything is strictly keept in sync, noticibly, it assumes that :\n- The software and fence.i  keep the hardware L1 instruction cache coherent\n- The software and sfence keep the hardware MMU TLB coherent\n\n# How to use\n\n```shell\nbuild/apps/rvls -f example/simple/trace.log\n```\n\n# Dependencies\n\n```shell\nsudo apt-get install device-tree-compiler libboost-all-dev\n\n# Install ELFIO, used to load elf file in the sim \ngit clone https://github.com/serge1/ELFIO.git\ncd ELFIO\ngit checkout d251da09a07dff40af0b63b8f6c8ae71d2d1938d # Avoid C++17\nsudo cp -R elfio /usr/include\n```\n\n# How to compile\n\n```shell\ngit clone https://github.com/SpinalHDL/rvls.git\ngit clone https://github.com/SpinalHDL/riscv-isa-sim.git --recursive\n\n# Compile riscv-isa-sim (spike), used as a golden model during the sim to check the dut behaviour (lock-step)\ncd riscv-isa-sim\nmkdir build\ncd build\n../configure --prefix=$RISCV --enable-commitlog  --without-boost --without-boost-asio --without-boost-regex\nmake -j$(nproc)\ncd ../..\n\n# Compile RVLS\ncd rvls\nmake -j$(nproc)\n\n# Demo\nbuild/apps/rvls -f example/simple/trace.log --spike-debug --spike-log\nhead -10 spike.log\n```\n   \n# JNI frontend\n\nYou can find the Java JNI interface in the [bindings/jni/rvls/jni/Frontend.java](bindings/jni/rvls/jni/Frontend.java) folder. It works in a very similar to the ASCII frontend excepted for the followings : \n- Commands a provided via JNI calls (no file involved)\n- Allows to check the behaviour of the SoC durring the simulation itself (lock-step) \n\n# ASCII frontend\n\nThere is a ASCII based frontend which can be used to feed the CPUs execution traces.\nIt consists into the simple lines of commands described bellow. \n\nSee [example/simple/trace.log](example/simple/trace.log) for an example of trace.\n\n## General commands\n\n`time $value`\n- Used to provide some sporatic timestap, just for debug purposes\n\n## Memory commands\n\n`elf load $offset_hex $path`\n\n`bin load $offset_hex $path`\n\n`memview new $memoryViewId $readIds $writeIds`\n- Create a new memory view\n- A memory view provide a representation of how a given memory master (ex CPU) observe the global memory content/ordering\n- readIds and writeIds represent the number of outstanding load/store that the CPU can have at most (LQ/SQ size)\n\n\n## RISC-V commands\n\nThere mostly 3 kind of RISC-V related commands :\n- The generals ones, to create a CPU / commit / trap\n- The ones to trace a register file read / write\n- The ones which are related to memory load / stores\n\n### general commands\n\n`rv new $hartId $isa $priv $physWidth $memoryViewId`\n- Create a new CPU\n- isa follow Spike, ex : RV32IMA\n- priv follow Spike, ex : MSU\n- physWidth specify the physical address memory width (32 bits max for now)\n- memoryViewId specify which memory view will be used by the CPU to do load/store\n\n`\"rv region add $hartId $kind $base_hex $size_hex\")`\n- Specify the memory regions for the given hart.\n- kind : 0=memory 1=io\n\n`rv set pc $hartId $pc_hex`\n- Used once after reset to specify where the CPU PC landed\n\n`rv commit $hartId $pc_hex`\n- Specify when a given hart commited an instruction\n\n`rv trap $hartId $interrupt $code`\n- Used for exception and interrupts traps\n\n`rv int set $hartId $intId $value`\n- Specify when hardware values of the input interrupts pins (external / timer interrupts)\n- intId follow the privileged spec mstatus CSR \n\n### Register file commands \n\n`rv rf w $hartId $rfKind $address $data_hex`\n- rfKind : 0 = int, 1 = float, 4 = csr \n- If address == 32 =\u003e don't check address\n\n`rv rf r $hartId $rfKind $address $data_hex`\n- rfKind : 0 = int, 1 = float, 4 = csr \n- If address == 32 =\u003e don't check address\n- Note that currently, only the reads to CSR should be logged\n\n### Load/Store commands\n`rv load exe $hartId $id $size $addr_hex $data_hex`\n- load exe meaning \"the moment at which the CPU readed a load value from the cache for a given LQ id\"\n- This is used by the cpu memory view to precisely figure out the memory ordering against other CPUs.\n\n`rv load com $hartId $id`\n- load com meaning \"the moment at which a given memory load is commited\"\n- should precede the related `rv commit` command\n\n`rv load flu $hartId`\n- load flu meaning \"Remove all the outstanding memory load, as the CPU flushed the LQ\"\n\n`rv store com $hartId $id $size $addr_hex $data_hex`\n- store com meaning \"A memory store commit\"\n- should precede the related `rv commit` command\n\n`rv store bro $hartId $id`\n- store bro meaning \"A memory store broadcast\"\n- Make the related store visible to all other memory views (used for memory ordering accross CPUs)\n\n`rv store sc $hartId $failure`\n- Specify if a given \"store conditional\" succeeded\n- should precede the related `rv commit` command\n\n`rv io $hartId $write $address_hex $data_hex $mask_hex $size $error`\n- Log the memory IO load/store accesses\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspinalhdl%2Frvls","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspinalhdl%2Frvls","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspinalhdl%2Frvls/lists"}