{"id":30894858,"url":"https://github.com/riscv-software-src/riscv-mirror-stf-library","last_synced_at":"2025-09-08T21:35:03.121Z","repository":{"id":311242458,"uuid":"1019661762","full_name":"riscv-software-src/riscv-mirror-stf-library","owner":"riscv-software-src","description":"Mirror of STF Library. The acronym STF stands for Simulation Trace Format. This is intended to be used with Sparta-based simulators, but that's not necessary.","archived":false,"fork":false,"pushed_at":"2025-08-23T00:39:41.000Z","size":984,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-23T02:48:15.362Z","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":"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":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-14T17:11:05.000Z","updated_at":"2025-08-23T00:39:44.000Z","dependencies_parsed_at":"2025-08-23T02:48:20.188Z","dependency_job_id":"03af27d5-63f2-4ace-9243-e7cca8df5399","html_url":"https://github.com/riscv-software-src/riscv-mirror-stf-library","commit_stats":null,"previous_names":["riscv-software-src/riscv-mirror-stf-library"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/riscv-software-src/riscv-mirror-stf-library","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riscv-software-src%2Friscv-mirror-stf-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riscv-software-src%2Friscv-mirror-stf-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riscv-software-src%2Friscv-mirror-stf-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riscv-software-src%2Friscv-mirror-stf-library/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-mirror-stf-library/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riscv-software-src%2Friscv-mirror-stf-library/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274231435,"owners_count":25245625,"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","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2025-09-08T21:35:00.873Z","updated_at":"2025-09-08T21:35:03.109Z","avatar_url":"https://github.com/riscv-software-src.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# STF Library\n\nThe acronym STF stands for Simulation Trace Format. This is intended to be used\nwith Sparta-based simulators, but that's not necessary.\n\nYou can view the STF specification at [stf_spec](https://github.com/sparcians/stf_spec).\n\nThis repo contains the following:\n\n1. Trace generators (writers)\n1. Trace consumers (readers)\n\n## Required Packages\n\nThe Docker images include all required packages.\n\nTo install on **Mac**:\n`brew install zstd`\n\nTo install on **Ubuntu**:\n`apt-get install zstd libzstd-dev`\n\nTo build documentation on **Ubuntu**:\n`apt install texlive-font-utils`\n\n## Building\n\n```\nmkdir release\ncd release\ncmake .. -DCMAKE_BUILD_TYPE=Release\nmake\n```\n## Quick Start on the API\n\n### Reading a Trace\n\nAPI documentation: `doc_doxygen/html/classstf_1_1STFInstReaderBase.html`\nExample Usage:\n```\n#include \"stf-inc/stf_inst_reader.hpp\"\n#include \"stf-inc/stf_record_types.hpp\"\n\nconstexpr bool skip_nonuser_mode = true; // example\nconstexpr bool CHECK_FOR_STF_PTE = false; // If true, search for an stf-pte file alongside this trace.\nconstexpr bool FILTER_MODE_CHANGE_EVENTS = true;\nconstexpr size_t BUFFER_SIZE = 4096;\nstf::STFInstReader reader(trace_filename,  // *.zstf, *.stf\n                          skip_nonuser_mode,\n                          CHECK_FOR_STF_PTE, \n                          FILTER_MODE_CHANGE_EVENTS,\n                          BUFFER_SIZE));\n\n// Iterate through the trace\nfor(const stf::STFInst \u0026 inst : reader) {\n    std::cout \u003c\u003c std::hex \u003c\u003c \"PC: 0x\" \u003c\u003c inst.pc() \u003c\u003c \" Opcode: 0x\" \u003c\u003c inst.opcode() \u003c\u003c std::endl;\n}\n\n```\n\n### Writing a Trace\n\nAPI documentation: `doc_doxygen/html/classstf_1_1STFWriter.html`\nExample Usage:\n```\n#include \"stf-inc/stf_writer.hpp\"\n#include \"stf-inc/stf_record_types.hpp\"\n\nuint64_t pc = 0x1000;\n\n////////////////////\n// Initialize/setup\n////////////////////\nstf::STFWriter stf_writer;\nstf_writer.open(\"my_trace.zstf\");  // If you do not want compression, drop the 'z': my_trace.stf\nstf_writer.addTraceInfo(stf::TraceInfoRecord(stf::STF_GEN::STF_GEN_IMPERAS, 1, 2, 0, \"Trace from Imperas\"));\nstf_writer.setISA(stf::ISA::RISCV);\n// make sure to setVLen when there are vector instructions in the trace \n// stf_writer.setVLen( /*VLEN*/ );\nstf_writer.setHeaderIEM(stf::INST_IEM::STF_INST_IEM_RV64);\nstf_writer.setTraceFeature(stf::TRACE_FEATURES::STF_CONTAIN_RV64);\nstf_writer.setTraceFeature(stf::TRACE_FEATURES::STF_CONTAIN_PHYSICAL_ADDRESS);\nstf_writer.setHeaderPC(pc);\nstf_writer.finalizeHeader();\n\n////////////////////\n// Write records\n////////////////////\n\n// Simple 32-bit add    x14,x12,x11\nstf_writer \u003c\u003c stf::InstRegRecord(11,\n                                 stf::Registers::STF_REG_TYPE::INTEGER,\n                                 stf::Registers::STF_REG_OPERAND_TYPE::REG_SOURCE,\n                                 x11_value);\nstf_writer \u003c\u003c stf::InstRegRecord(12,\n                                 stf::Registers::STF_REG_TYPE::INTEGER,\n                                 stf::Registers::STF_REG_OPERAND_TYPE::REG_SOURCE,\n                                 x12_value);\nstf_writer \u003c\u003c stf::InstRegRecord(14,\n                                 stf::Registers::STF_REG_TYPE::INTEGER,\n                                 stf::Registers::STF_REG_OPERAND_TYPE::REG_DEST,\n                                 x14_value);\nstf_writer \u003c\u003c stf::InstOpcode32Record(0x00b60733);\n\n// A branch\nstf_writer \u003c\u003c stf::InstPCTargetRecord(branch_target_pc);\nstf_writer \u003c\u003c stf::InstOpcode32Record(0xfee59ce3);\n\n```\n\n## Unit Tests for STF_LIB\n\nA regression target `regress` is available for unit testing STF_LIB. These tests are based on CTest and can be run using the following commands:\n\n```sh\nmkdir -p release/\ncd release/\ncmake .. -DCMAKE_BUILD_TYPE=Release\nmake -j32 regress\ncd ..\n```\n\nThis setup provides a stub of CTest-based unit tests to ensure the functionality and reliability of the library. Please note that these tests do not yet cover the STF_LIB extensively and are currently just a stub.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friscv-software-src%2Friscv-mirror-stf-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friscv-software-src%2Friscv-mirror-stf-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friscv-software-src%2Friscv-mirror-stf-library/lists"}