A RISC-V Functional Model, but different...
,
|`\
/'_/_
,'_/\_/\_ ,
,'_/\'_\_,/_ ,'|
,'_/\_'_ \_ \_/ _,-'_/
,'_/'\_'_ \_ \'_,\ _,-'_,-/ \,
,' /_\ _'_ \_ \'_,/ __,-'<_,' _,\_,/
( (' )\/(_ \_ \'_,\ __--' _,-_/_,-',_/ _\
\_`\> 6` 7 \'_,/ ,-' _,-,'\,_'_ \,_/'_,\
\/- _/ 7 '/ _,' _/'\_ \,_'_ \_ \'_,/
\_'/> 7'_/' _/' \_ '\,_'_ \_ \'_,\
>/ _ ,V ,< \__ '\,_'_ \_ \'_,/
/'_ ( )_)\/-,',__ '\,_'_,\_,\'_\
( ) \_ \|_ `\_ \_,/'\,_'_,/'
\\_ \_\_) `\_
\_) > `\_
/ `, |`\_
/ \ / \ `\
/ __/| / / `\
(` ( (` (_ \ /
/ ,/ | / / \
/ ,/ | / \ `\_
_/_/ |/ /__/,_/
/_( /_(
____
| _ \ ___ __ _ __ _ ___ _ _ ___
| |_) / _ \/ _` |/ _` / __| | | / __|
| __/ __/ (_| | (_| \__ \ |_| \__ \
|_| \___|\__, |\__,_|___/\__,_|___/
|___/
Pegasus is an open-source functional simulator, built using the Sparta Modeling Framework, designed for the purpose of co-simulation, STF trace generation, and application development. The main drivers or use cases are Design Verification and Execution-Driven Mode (EDM) performance simulators like Olympia.
Pegasus can be used to execute instructions in a holistic fashion or in partial stages. For example, setting Pegasus to execute an instruction at address 0x1000 actually entails many steps, especially for memory operations:
- Instruction Translation
- Can take an exception: access permission, miss in the MMU, etc
- Can invoke a TLB walk
- Data fetch for the instruction
- Can encounter an external exception
- Can miss in cache
- Decode
- Can take an exception: illop, invalid opcode
- Execute
- Instruction address generation for memory accesses
- Instruction translation for memory accesses: can take an exception
- Instruction data access: can miss in the cache
- Instruction execution itself: can take an exception
- Redirection or sequential PC
In most, if not all, functional simulators developed in the industry
perform all of the operations above during a single call to step().
Pegasus is different. Pegasus can stop at any point in the flow above
and return control back to the caller. For example, if the user wants
to run simulation until a load instruction is about to access memory,
the user can advance Pegasus until that point and then stop.
"Continuing" the simulator re-enters that access point.
In addition, with each full step of an instruction, an Event object is returned detailing what the instruction did on its journey through the stages. This event can be used to “undo” or backup the simulator as need be. This allows out-of-order simulators like Olympia to have multiple paths of execution through a binary (think branch mispredictions).
Pegasus is still under development and more documentation and support will come; stay tuned!
Install the following packages (tested with Ubuntu 24.04):
- (apt-get install cmake) cmake v3.22
- (apt-get install clang) Clang, Version: 14.0.0
- (apt-get install libboost-all-dev) boost 1.74.0
- (apt-get install libyaml-cpp-dev) YAML CPP 0.7.0
- (apt-get install rapidjson-dev) RapidJSON CPP 1.1.0
- (apt-get install libsqlite3-dev) SQLite3 3.37.2
- (apt-get install libhdf5-dev) HDF5 1.10.7
A Pegasus Conda environment is also available:
conda env create -f conda/pegasus_env.yaml
conda activate pegasus
Download and build sparta, map_v2.1:
git clone git@github.com:sparcians/map --recursive --branch map_v2.1
cd map/sparta
mkdir release
cd release
CC=$COMPILER CXX=$CXX_COMPILER cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local/
sudo make -j$(nproc --all) install
If using Conda, you must install Sparta in the Pegasus Conda environment:
cmake --install . --prefix $CONDA_PREFIX
git clone git@github.com:sparcians/pegasus.git --recursive
cd pegasus
mkdir release
cd release
cmake .. -DCMAKE_BUILD_TYPE=Release -DSPARTA_SEARCH_DIR=/usr/local
make
make pegasus_regress
Alternatively, you can build Pegasus without an install of Sparta by providing a path
to your Sparta repo and Pegasus will build the Sparta library for
you. Since Sparta already has a make target named regress, the Pegasus
regression make target is renamed to pegasus_regress.
mkdir release
cd release
cmake .. -DCMAKE_BUILD_TYPE=Release -DSPARTA_SEARCH_DIR=<full path to map/sparta>
make
make pegasus_regress
The RISC-V unit tests (riscv-software-src/riscv-tests) are a set of self-checking unit tests provided by the RISC-V Foundation. Follow the directions in the README to build the tests.
cd pegasus/<build>/sim
python ../../scripts/RunArchTest.py --riscv-arch $RISCV_TESTS_PATH/isa/
The Tenstorrent architectural tests (tenstorrent/riscv_arch_tests) are a set of self-checking architectural tests provided by Tenstorrent. Follow the directions in the README to build the tests. Alternatively, pre-built tests can be downloaded here: Releases/v0.2.0+aligned-access
cd pegasus/<build>/sim
python ../../scripts/RunArchTest.py --tenstorrent $TENSTORRENT_TESTS_PATH/bare_metal/user/
To build Pegasus for debugging, Debug and FastDebug build types are available.
CC=clang CXX=clang++ cmake .. -DCMAKE_BUILD_TYPE=FastDebug
CC=clang CXX=clang++ cmake .. -DCMAKE_BUILD_TYPE=Debug
| RVA23U64 Mandatory Extensions | Status |
|---|---|
| M Integer multiplication and division. | ✅ |
| A Atomic instructions. | ✅ |
| F Single-precision floating-point instructions. | ✅ |
| D Double-precision floating-point instructions. | ✅ |
| C Compressed instructions. | ✅ |
| B Bit-manipulation instructions. | ✅ |
| Zicsr CSR instructions. These are implied by presence of F. | ✅ |
| Zicntr Base counters and timers. | ❌ |
| Zihpm Hardware performance counters. | ❌ |
| Ziccif Main memory regions with both the cacheability and coherence PMAs must support instruction fetch, and any instruction fetches of naturally aligned power-of-2 sizes up to min(ILEN,XLEN) (i.e., 32 bits for RVA23) are atomic. | ❌ |
| Ziccrse Main memory regions with both the cacheability and coherence PMAs must support RsrvEventual. | ❌ |
| Ziccamoa Main memory regions with both the cacheability and coherence PMAs must support all atomics in A. | ❌ |
| Zicclsm Misaligned loads and stores to main memory regions with both the cacheability and coherence PMAs must be supported. | ❌ |
| Za64rs Reservation sets are contiguous, naturally aligned, and a maximum of 64 bytes. | ❌ |
| Zihintpause Pause hint. | ❌ |
| Zic64b Cache blocks must be 64 bytes in size, naturally aligned in the address space. | ❌ |
| Zicbom Cache-block management instructions. | ✅ |
| Zicbop Cache-block prefetch instructions. | ✅ |
| Zicboz Cache-Block Zero Instructions. | ✅ |
| Zfhmin Half-precision floating-point. | ❌ |
| Zkt Data-independent execution latency. | ❌ |
| V Vector extension. | ❌ |
| Zvfhmin Vector minimal half-precision floating-point. | ❌ |
| Zvbb Vector basic bit-manipulation instructions. | ❌ |
| Zvkt Vector data-independent execution latency. | ❌ |
| Zihintntl Non-temporal locality hints. | ❌ |
| Zicond Integer conditional operations. | ✅ |
| Zimop may-be-operations. | ❌ |
| Zcmop Compressed may-be-operations. | ❌ |
| Zcb Additional compressed instructions. | ✅ |
| Zfa Additional floating-Point instructions. | ❌ |
| Zawrs Wait-on-reservation-set instructions. | ❌ |
| Supm Pointer masking, with the execution environment providing a means to select PMLEN=0 and PMLEN=7 at minimum. | ❌ |
| RVA23U64 Optional Extensions | Status |
|---|---|
| Zvkng Vector crypto NIST algorithms with GCM. | ❌ |
| Zvksg Vector crypto ShangMi algorithms with GCM. | ❌ |
| Zabha Byte and halfword atomic memory operations. | ❌ |
| Zacas Compare-and-Swap instructions. | ❌ |
| Ziccamoc Main memory regions with both the cacheability and coherence PMAs must provide AMOCASQ level PMA support. | ❌ |
| Zvbc Vector carryless multiplication. | ❌ |
| Zama16b Misaligned loads, stores, and AMOs to main memory regions that do not cross a naturally aligned 16-byte boundary are atomic. | ❌ |
| Zfh Scalar half-precision floating-point. | ❌ |
| Zbc Scalar carryless multiply. | ❌ |
| Zicfilp Landing Pads. | ❌ |
| Zicfiss Shadow Stack. | ❌ |
| Zvfh Vector half-precision floating-point. | ❌ |
| Zfbfmin Scalar BF16 converts. | ❌ |
| Zvfbfmin Vector BF16 converts. | ❌ |
| Zvfbfwma Vector BF16 widening mul-add. | ❌ |
| RVA23S64 Mandatory Extensions | Status |
|---|---|
| Zifencei Instruction-Fetch Fence. | ✅ |
| Svbare The satp mode Bare must be supported. | ✅ |
| Sv39 Page-based 39-bit virtual-Memory system. | ✅ |
| Svade Page-fault exceptions are raised when a page is accessed when A bit is clear, or written when D bit is clear. | ❌ |
| Ssccptr Main memory regions with both the cacheability and coherence PMAs must support hardware page-table reads. | ❌ |
| Sstvecd stvec.MODE must be capable of holding the value 0 (Direct). When stvec.MODE=Direct, stvec.BASE must be capable of holding any valid four-byte-aligned address. | ❌ |
| Sstvala stval must be written with the faulting virtual address for load, store, and instruction page-fault, access-fault, and misaligned exceptions, and for breakpoint exceptions other than those caused by execution of the EBREAK or C.EBREAK instructions. For virtual-instruction and illegal-instruction exceptions, stval must be written with the faulting instruction. | ❌ |
| Sscounterenw For any hpmcounter that is not read-only zero, the corresponding bit in scounteren must be writable. | ❌ |
| Svpbmt Page-based memory types | |
| Svinval Fine-grained address-translation cache invalidation. | ❌ |
| Svnapot NAPOT translation contiguity. | ❌ |
| Sstc supervisor-mode timer interrupts. | ❌ |
| Sscofpmf count overflow and mode-based filtering. | ❌ |
| Ssnpm Pointer masking, with senvcfg.PME and henvcfg.PME supporting, at minimum, settings PMLEN=0 and PMLEN=7. | ❌ |
| Ssu64xl sstatus.UXL must be capable of holding the value 2 (i.e., UXLEN=64 must be supported). | ❌ |
| H The hypervisor extension. | ❌ |
| Ssstateen Supervisor-mode view of the state-enable extension. The supervisor-mode (sstateen10-3 and hypervisor-mode (hstateen0-3) state-enable registers must be provided. | ❌ |
| Shcounterenw For any hpmcounter that is not read-only zero, the corresponding bit in hcounteren | |
| must be writable. | |
| Shvstvala vstval must be written in all cases described above for stval. | |
| Shtvala htval must be written with the faulting guest physical address in all circumstances permitted by the ISA. | |
| Shvstvecd vstvec.MODE must be capable of holding the value 0 (Direct). When vstvec.MODE=Direct, vstvec.BASE must be capable of holding any valid four-byte-aligned address. | |
| Shvsatpa All translation modes supported in satp must be supported in vsatp. | |
| Shgatpa For each supported virtual memory scheme SvNN supported in satp, the corresponding hgatp SvNNx4 mode must be supported. The hgatp mode Bare must also be supported. | ❌ |
| RVA23S64 Optional Extensions | Status |
|---|---|
| Sv48 Page-based 48-bit virtual-memory system. | ✅ |
| Sv57 Page-based 57-bit virtual-memory system. | ✅ |
| Zkr Entropy CSR. | ❌ |
| Svadu Hardware A/D bit updates. | ❌ |
| Sdtrig Debug triggers. | ❌ |
| Ssstrict No non-conforming extensions are present. Attempts to execute unimplemented opcodes or access unimplemented CSRs in the standard or reserved encoding spaces raises an illegal instruction exception that results in a contained trap to the supervisor-mode trap handler. | ❌ |
| Svvptc Transitions from invalid to valid PTEs will be visible in bounded time without an explicit memory-management fence. | |
| Sspm Supervisor-mode pointer masking, with the supervisor execution environment providing a | |
| means to select PMLEN=0 and PMLEN=7 at minimum. |