{"id":13644871,"url":"https://github.com/riscv-software-src/riscv-perf-model","last_synced_at":"2025-04-04T17:04:48.865Z","repository":{"id":63790692,"uuid":"525061814","full_name":"riscv-software-src/riscv-perf-model","owner":"riscv-software-src","description":"Example RISC-V Out-of-Order/Superscalar Processor Performance Core and MSS Model","archived":false,"fork":false,"pushed_at":"2025-03-25T15:06:09.000Z","size":2132,"stargazers_count":158,"open_issues_count":38,"forks_count":65,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-03-28T16:08:48.693Z","etag":null,"topics":["modeling","out-of-order","performance-analysis","risc-v"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/riscv-software-src.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-15T16:37:08.000Z","updated_at":"2025-03-28T07:58:05.000Z","dependencies_parsed_at":"2024-02-12T21:58:04.819Z","dependency_job_id":"e266e159-fd50-4967-b8e0-e142257b3fb5","html_url":"https://github.com/riscv-software-src/riscv-perf-model","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":"riscv-software-src/template-riscv-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riscv-software-src%2Friscv-perf-model","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riscv-software-src%2Friscv-perf-model/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riscv-software-src%2Friscv-perf-model/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riscv-software-src%2Friscv-perf-model/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/riscv-software-src","download_url":"https://codeload.github.com/riscv-software-src/riscv-perf-model/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217172,"owners_count":20903008,"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":["modeling","out-of-order","performance-analysis","risc-v"],"created_at":"2024-08-02T01:02:17.042Z","updated_at":"2025-04-04T17:04:48.847Z","avatar_url":"https://github.com/riscv-software-src.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"[![Regress Olympia on Ubuntu](https://github.com/riscv-software-src/riscv-perf-model/actions/workflows/ubuntu-build.yml/badge.svg)](https://github.com/riscv-software-src/riscv-perf-model/actions/workflows/ubuntu-build.yml)\n\n# olympia\n\nOlympia is a Performance Model written in C++ for the RISC-V community as an\n_example_ of an Out-of-Order RISC-V CPU Performance Model based on the\n[Sparta Modeling\nFramework](https://github.com/sparcians/map/tree/master/sparta).\n\nOlympia's intent is to provide a starting point for RISC-V CPU performance modeling development\nenabling the community to build upon Olympia by extending its\nfunctionality in areas like branch prediction, prefetching/caching\nconcepts, application profiling, middle-core design, etc.\n\nCurrently, Olympia is a _trace-driven_ simulator running instructions\nstreams provided in either [JSON\nformat](https://github.com/riscv-software-src/riscv-perf-model/tree/master/traces#json-inputs)\nor [STF](https://github.com/sparcians/stf_spec).  However, extending\nOlympia with a functional back-end to run applications natively is\nunder development.\n\n## Building\n\n1. Set up a clean working `conda` environment by following the directions [here](https://github.com/riscv-software-src/riscv-perf-model/tree/master/conda)\n1. Download and build Sparta and checkout branch [map_v2](https://github.com/sparcians/map/tree/map_v2).  Follow the directions on the [Sparta README](https://github.com/sparcians/map/tree/map_v2#building-map) to build _and install_ Sparta\n1. Make sure you have the [required libraries](https://github.com/sparcians/stf_lib#required-packages) for the STF toolsuite installed\n1. Clone olympia\n   ```\n   git clone --recursive git@github.com:riscv-software-src/riscv-perf-model.git\n   ```\n1. Build Olympia in the new `conda` environment created\n\n```\n\n################################################################################\n# Enable conda environment (suggested)\nconda activate sparta\n\n################################################################################\n# Optimized, no symbols\n\n# A release build\nmkdir release; cd release\n\n# Assumes sparta was installed in the conda environment.\n# If not, use -DSPARTA_SEARCH_DIR=/path/to/sparta/install\ncmake .. -DCMAKE_BUILD_TYPE=Release\n\n# Just builds the simulator\nmake olympia\n\n################################################################################\n# Fast Debug, optimized (not LTO) with debug symbols\n\n# A FastDebug build\nmkdir fastdebug; cd fastdebug\n\n# Assumes sparta was installed in the conda environment.\n# If not, use -DSPARTA_SEARCH_DIR=/path/to/sparta/install\ncmake .. -DCMAKE_BUILD_TYPE=fastdebug\n\n# Just builds the simulator\nmake olympia\n\n################################################################################\n# Debug\n\n# A debug build\nmkdir debug; cd debug\n\n# Assumes sparta was installed in the conda environment.\n# If not, use -DSPARTA_SEARCH_DIR=/path/to/sparta/install\ncmake .. -DCMAKE_BUILD_TYPE=Debug\n\n# Just builds the simulator\nmake olympia\n\n################################################################################\n# Regression\nmake regress\n\n```\n\n## Developing\n\nDeveloping on Olympia is encouraged!  Please check out the\n[Issue](https://github.com/riscv-software-src/riscv-perf-model/issues)\nsection for areas of needed contributions.  If there is no Assignee,\nthe work isn't being done!\n\nWhen developing on Olympia, please adhere to the documented [Coding\nStyle Guidelines](./CodingStyle.md).\n\n## Example Usage\n\n### Get Help Messages\n```\n./olympia --help                  # Full help\n./olympia --help-brief            # Brief help\n./olympia --help-topic topics     # Topics to get detailed help on\n./olympia --help-topic parameters # Help on parameters\n```\n\n### Get Simulation Layout\n```\n./olympia --show-tree       --no-run # Show the full tree; do not run the simulator\n./olympia --show-parameters --no-run # Show the parameter tree; do not run the simulator\n./olympia --show-loggers    --no-run # Show the loggers; do not run the simulator\n# ... more --show options; see help\n```\n\n### Running\n\n```\n# Run a given JSON \"trace\" file\n./olympia ../traces/example_json.json\n\n# Run a given STF trace file\n./olympia ../traces/dhry_riscv.zstf\n\n# Run a given STF trace file only 100K instructions\n./olympia -i100K ../traces/dhry_riscv.zstf\n\n# Run a given STF trace file and generate a\n# generic full simulation report\n./olympia ../traces/dhry_riscv.zstf --report-all dhry_report.out\n```\n\n### Generate and Consume Configuration Files\n\n```\n# Generate a baseline config\n./olympia --write-final-config baseline.yaml --no-run\n\n# Generate a config with a parameter change\n./olympia -p top.cpu.core0.lsu.params.tlb_always_hit true --write-final-config always_hit_DL1.yaml --no-run\ndyff between baseline.yaml always_hit_DL1.yaml\n\n# Use the configuration file generated\n./olympia -c always_hit_DL1.yaml -i1M ../traces/dhry_riscv.zstf\n```\n\n### Generate Logs\n```\n# Log of all messages, different outputs\n./olympia -i1K --auto-summary off ../traces/dhry_riscv.zstf \\\n   -l top info all_messages.log.basic   \\\n   -l top info all_messages.log.verbose \\\n   -l top info all_messages.log.raw\n\n# Different logs, some shared\n./olympia -i1K --auto-summary off ../traces/dhry_riscv.zstf \\\n   -l top.*.*.decode info decode.log \\\n   -l top.*.*.rob    info rob.log    \\\n   -l top.*.*.decode info decode_rob.log \\\n   -l top.*.*.rob    info decode_rob.log\n```\n### Generate PEvents (for Correlation)\n\nPEvents or Performance Events are part of the Sparta Modeling\nFramework typically used to correlate a performance model with RTL.\nUnlike pipeout collection Name/Value Definition Pairs (see an example\nin\n[Inst.hpp](https://github.com/riscv-software-src/riscv-perf-model/blob/db6c2f1878381389966544d7844c7d10c557083e/core/Inst.hpp#L330)),\nPEvent Name/Value Definitions are typically more compact.  Below the\nsurface, Sparta uses the logging infrastructure to collect the data.\n\nOlympia has instrumented a few PEvents as an example.  The following\ncommands are useful in listing/using this functionality.\n\n```\n# Dump the list of supported PEvents\n./olympia --help-pevents --no-run\n\n# Generate RETIRE only pevents for the first 100 instructions of Dhrystone\n./olympia traces/dhry_riscv.zstf --pevents retire.out RETIRE -i100\n\n# Generate COMPLETE only pevents ...\n./olympia traces/dhry_riscv.zstf --pevents complete.out COMPLETE -i100\n\n# Generate COMPLETE pevents into complete.out and RETIRE pevents into retire.out ...\n./olympia traces/dhry_riscv.zstf --pevents retire.out RETIRE --pevents complete.out COMPLETE -i100\n\n# Generate RETIRE and COMPLETE pevents to the same file\n./olympia traces/dhry_riscv.zstf --pevents complete_retire.out RETIRE,COMPLETE -i100\n\n# Generate all pevents\n./olympia traces/dhry_riscv.zstf --pevents complete_retire.out all -i100\n```\n\n### Generate Reports\n```\n# Run with 1M instructions, generate a report from the top of the tree\n# with stats that are not hidden; turn off the auto reporting\ncat reports/core_stats.yaml\n./olympia -i1M ../traces/dhry_riscv.zstf --auto-summary off  --report \"top\" reports/core_stats.yaml my_full_report.txt text\n\n# Generate a report only for decode in text form\n./olympia -i1M ../traces/dhry_riscv.zstf --auto-summary off  --report \"top.cpu.core0.decode\" reports/core_stats.yaml my_decode_report.txt text\n\n# Generate a report in JSON format\n./olympia -i1M ../traces/dhry_riscv.zstf --auto-summary off  --report \"top\" reports/core_stats.yaml my_json_report.json json\n\n# Generate a report in CSV format\n./olympia -i1M ../traces/dhry_riscv.zstf --auto-summary off  --report \"top\" reports/core_stats.yaml my_csv_report.csv csv\n\n# Generate a report in HTML format\n./olympia -i1M ../traces/dhry_riscv.zstf --auto-summary off  --report \"top\" reports/core_stats.yaml my_html_report.html html\n```\n\n### Generate More Complex Reports\n```\n# Using a report definition file, program the report collection to\n# start after 500K instructions\ncat reports/core_report.def\n./olympia -i1M ../traces/dhry_riscv.zstf --auto-summary off    \\\n   --report reports/core_report.def  \\\n   --report-search reports           \\\n   --report-yaml-replacements        \\\n       OUT_BASE my_report            \\\n       OUT_FORMAT text               \\\n       INST_START 500K\n\n# Generate a time-series report -- capture all stats every 10K instructions\ncat reports/core_timeseries.def\n./olympia -i1M ../traces/dhry_riscv.zstf --auto-summary off       \\\n   --report reports/core_timeseries.def \\\n   --report-search reports              \\\n   --report-yaml-replacements           \\\n       OUT_BASE my_report               \\\n       TS_PERIOD 10K\npython3 ./reports/plot_ts.y my_report_time_series_all.csv\n```\n\n### Experimenting with Architectures\n```\n# By default, olympia uses the small_core architecture\n./olympia -i1M  ../traces/dhry_riscv.zstf --auto-summary off --report-all report_small.out\n\n# Use the medium sized core\ncat arches/medium_core.yaml  # Example of the medium core\n./olympia -i1M  ../traces/dhry_riscv.zstf --arch medium_core --auto-summary off --report-all report_medium.out\ndiff -y -W 150 report_small.out report_medium.out\n\n# Use the big core\ncat arches/big_core.yaml  # Example of the big core\n./olympia -i1M  ../traces/dhry_riscv.zstf --arch big_core --auto-summary off --report-all report_big.out\ndiff -y -W 150 report_medium.out report_big.out\n\n```\n\n### Generate and View a Pipeout\n```\n./olympia -i1M ../traces/dhry_riscv.zstf --debug-on-icount 100K -i 101K -z pipeout_1K --auto-summary off\n\n# Launch the viewer\n# *** MacOS use pythonw\npython $MAP_BASE/helios/pipeViewer/pipe_view/argos.py -d pipeout_1K -l ../layouts/small_core.alf\n```\n\n### Issue Queue Modeling\nOlympia has the ability to define issue queue to execution pipe mapping, as well as what pipe targets are available per execution unit. Also, with the implemenation of issue queue, Olympia now has a generic execution unit for all types, so one doesn't have to define `alu0` or `fpu0`, it is purely based off of the pipe targets, instead of unit types as before.\nIn the example below:\n```\ntop.cpu.core0.extension.core_extensions:\n  # this sets the pipe targets for each execution unit\n  # you can set a multiple or just one:\n  # [\"int\", \"div\"] would mean this execution pipe can accept\n  # targets of: \"int\" and \"div\"\n  pipelines:\n  [\n    [\"int\"], # exe0\n    [\"int\", \"div\"], # exe1\n    [\"int\", \"mul\"], # exe2\n    [\"int\", \"mul\", \"i2f\", \"cmov\"], # exe3\n    [\"int\"], # exe4\n    [\"int\"], # exe5\n    [\"float\", \"faddsub\", \"fmac\"], # exe6\n    [\"float\", \"f2i\"], # exe7\n    [\"br\"], # exe8\n    [\"br\"] # exe9\n  ]\n  # this is used to set how many units per queue\n  # [\"0\", \"3\"] means iq0 has exe0, exe1, exe2, and exe3, so it's inclusive\n  # if you want just one execution unit to issue queue you can do:\n  # [\"0\"] which would result in iq0 -\u003e exe0\n  # *note if you change the number of issue queues, \n  # you need to add it to latency matrix below\n\n  issue_queue_to_pipe_map:\n  [ \n    [\"0\", \"1\"], # iq0 -\u003e exe0, exe1\n    [\"2\", \"3\"], # iq1 -\u003e exe2, exe3\n    [\"4\", \"5\"], # iq2 -\u003e exe4, exe5\n    [\"6\", \"7\"], # iq3 -\u003e exe6, exe7\n    [\"8\", \"9\"]  # iq4 -\u003e exe8, exe9\n  ]\n```\n\nThe `pipelines` section defines for each execution unit, what are it's pipe targets. For example, the first row that has `[\"int\"]` defines the first execution unit `exe0` that only handles instructions with pipe targets of `int`. Additionally, the second row defines an execution unit that handles instructions of `int` and `div` and so on.\n\nThe `issue_queue_to_pipe_map` defines which execution units map to which issue queues, with the position being the issue queue number. So in the above `[\"0\", \"1\"]` in the first row is the first issue queue that connects to `exe0` and `exe1`, so do note it's inclusive of the end value. If one wanted to have a one execution unit to issue queue mapping, the above would turn into:\n```\nissue_queue_to_pipe_map:\n  [ \n    [\"0\"], # iq0 -\u003e exe0\n    [\"1\"], # iq1 -\u003e exe1\n    [\"2\"], # iq2 -\u003e exe2\n    [\"3\"], # iq3 -\u003e exe3\n    [\"4\"], # iq4 -\u003e exe4\n    [\"5\"], # iq5 -\u003e exe5\n    [\"6\"], # iq6 -\u003e exe6\n    [\"7\"], # iq7 -\u003e exe7\n    [\"8\"], # iq8 -\u003e exe8\n    [\"9\"], # iq9 -\u003e exe9\n  ]\n```\n\nAdditionally, one can rename the issue queues and execution units to more descriptive names of their use such as:\n```\nexe_pipe_rename:\n  [\n    [\"exe0\", \"alu0\"],\n    [\"exe1\", \"alu1\"],\n    [\"exe2\", \"alu2\"],\n    [\"exe3\", \"alu3\"],\n    [\"exe4\", \"alu4\"],\n    [\"exe5\", \"alu5\"],\n    [\"exe6\", \"fpu0\"],\n    [\"exe7\", \"fpu1\"],\n    [\"exe8\", \"br0\"],\n    [\"exe9\", \"br1\"],\n  ]\n\n  # optional if you want to rename each iq* unit\n  issue_queue_rename:\n  [\n    [\"iq0\", \"iq0_alu\"],\n    [\"iq1\", \"iq1_alu\"],\n    [\"iq2\", \"iq2_alu\"],\n    [\"iq3\", \"iq3_fpu\"],\n    [\"iq4\", \"iq4_br\"],\n  ]\n```\nThe above shows a 1 to 1 mapping of the renaming the execution units and issue queues. Do keep in mind that the order does matter, so you have to rename it exe0, exe1 and in order. Additionally, you have to either rename all execution units or all issue queue units, you cannot do partial. You can rename only the execution units but not the issue queues.\n\nFinally, if you do rename the issue queue names, you will need to update their definition in the scoreboard as so:\n```\ntop.cpu.core0.rename.scoreboards:\n  # From\n  # |\n  # V\n  integer.params.latency_matrix: |\n      [[\"\",         \"lsu\",     \"iq0_alu\", \"iq1_alu\", \"iq2_alu\", \"iq3_fpu\", \"iq4_br\"],\n      [\"lsu\",       1,         1,         1,          1,        1,         1],\n      [\"iq0_alu\",   1,         1,         1,          1,        1,         1],\n      [\"iq1_alu\",   1,         1,         1,          1,        1,         1],\n      [\"iq2_alu\",   1,         1,         1,          1,        1,         1],\n      [\"iq3_fpu\",   1,         1,         1,          1,        1,         1],\n      [\"iq4_br\",    1,         1,         1,          1,        1,         1]]\n  float.params.latency_matrix: |\n      [[\"\",         \"lsu\",     \"iq0_alu\", \"iq1_alu\", \"iq2_alu\", \"iq3_fpu\", \"iq4_br\"],\n      [\"lsu\",       1,         1,         1,          1,        1,         1],\n      [\"iq0_alu\",   1,         1,         1,          1,        1,         1],\n      [\"iq1_alu\",   1,         1,         1,          1,        1,         1],\n      [\"iq2_alu\",   1,         1,         1,          1,        1,         1],\n      [\"iq3_fpu\",   1,         1,         1,          1,        1,         1],\n      [\"iq4_br\",    1,         1,         1,          1,        1,         1]]\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friscv-software-src%2Friscv-perf-model","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friscv-software-src%2Friscv-perf-model","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friscv-software-src%2Friscv-perf-model/lists"}