Five EmbedDev

Building a header-only C++20 coroutine runtime for bare-metal RISC-V

2024-11-24T00:00:00+00:00

Creating the coroutines runtime infrastructure

A simple coroutine example was presented in “C++20 coroutines, header only, without an OS”. This post describes the runtime used for that example in detail.

This story is also published on Medium.

Summary of the runtime files

The runtime for this example is a set of include files in include/coro. These files are used:

nop_task.hpp : Task structure including promise_type to conform the C++ coroutines task concept.
scheduler.hpp : Generic scheduler class that can manage a set of std::coroutine_handle to determine when they should resume and implement the resumption.
awaitable_timer.hpp : An “awaitable” class that can be used with co_await to schedule a coroutines to wake up after a given std::chono delay.
static_list.hpp: An alternative to std::list that uses custom memory allocation from a static region to avoid heap usage.
awaitable_priority.hpp: An alternative “awaitable” class for tasks to be scheduled to wake according to priority.

NOTE: All classes here are designed to not use the heap for allocation. They will allocate all memory from statically declared buffers.

The coroutine task concept

The nop_task class in nop_task.hpp file implements the coroutine task concept.

A coroutine task includes a promise concept with no return values. The important structures in this file arestruct nop_task / struct nop_task::promise_type. This is implemented as described in CPP Reference.

This task structure will be allocated each time a coroutine is called. To avoid heap allocation static memory allocation is used (to be described below). When using a memory constrained platform it is important to understand that the number of coroutines that can be called is restricted by the memory allocated for nop_task::task_heap_.

The relationships between the task classes is shown in the following class diagram:

The awaitable concept

The classes in awaitable_timer.hpp and awaitable_priority.hpp represent asynchronous events that pause the coroutine task until an event occurs.

These classes are designed to be returned from a co_await, this ensures a task can be scheduled to be resumed on a later event.

The awaitable_timer class implements the awaitable concept described in CPP Reference, and also the co_await operator that is overloaded to take the scheduler_delay struct and return awaitable_timer. An additional concept of the scheduler class is being used to manage the coroutine handle and wake up conditions that are used to implement coroutine task pause.

The relationships between the awaitable classes is shown in the following class diagram:

The scheduler class

The classes in scheduler.hpp are designed to do the work of managing the coroutines that are paused. It is a template class, parameterized according to the type of event that should be scheduled, and the maximum number of concurrent active tasks.

The scheduler does the work that would be done by an RTOS or General Purpose OS. It manages a task list of waiting tasks with wake conditions and resumes them on the wake event.

The awaitable classes, introduced above, will insert paused tasks via insert(). The active execution context must call resume() to resume the paused tasks. Each entry in the task list is a schedule_entry structure. The classe are templates specialized by the wake up condition.

This scheduler class is not a concept required by C++ coroutines, but in this example it is needed as there is no operating system scheduler.

The relationships between scheduler classes is shown in the following class diagram:

Using the awaitable and scheduler classes to create a software timer

The awaitable class and scheduler are combined to implement the software timer feature. The following diagram shows how the classes relate.

Walk through of the detailed sequence of suspend and resume

Now the concrete classes have been defined, the sequence to suspend and resume a coroutine class can be show.

It is shown below in 3 stages in relation to the simple timer example.

1. Setup a coroutine, and suspend on the first wait.

2. Resume and suspend, iterate over several time delays.

3. Complete iterating and exit coroutines.

Testing

The runtime has some basic unit testing implemented in test using the unity test framework. The tests are not comprehensive, but run independent of hardware as the runtime is host & OS independent. The tests are compiled for the host OS and run locally.

Summary

The runtime presented in this article is not meant for production usage and has the bare minimal functionality to implement a re-entrant function using a software timer.

However, it does show the potential of C++ coroutines to be applied to real time applications that are portable across different OS and target architectures.

Appendix

References

I won’t explain the details of C++ coroutines, there are much better resources. I used the following to understand coroutines:

A Few implementation details

Tasks are created at the first call to an asynchronous routine. The allocated task data structure is minimal.
Tasks do not have a dedicated stack, they will be restored to the stack where they are woken.
Context switching stack management is implemented by the compiler, no custom assembler routines are needed (such as portASM.s in FreeRTOS). This is possible as there is no pre-emptive context switching.
The scheduler can be made a C++ object, and context switching can be controlled programmatically..

Exploring C++20 coroutines for embedded and bare-metal development on RISC-V platforms

2024-11-24T00:00:00+00:00

Introduction

This post is about using C++ coroutines to suspend and resume functions in real time. The objective is a simple way of building real time tasks using only C++, without the need for an RTOS or operating system kernel.

Coroutines are functions that can be suspended and resumed, using the keywords co_await, co_yield and co_return. The C++20 standard introduced coroutines to the language.

C++ standardized the keywords and type concepts for coroutines, but it did not standardize a runtime¹. The lack of a standard runtime has made them hard to use them “out of the box”, but the implementation of coroutines is very adaptable to different use cases.

Here I use a simple runtime implementing C++20 coroutines on bare metal (no operating system) for RISC-V, using the co_await keyword. This is done by passing the real time scheduler and resume time condition as the argument to the asynchronous wait operator.

The runtime is described in detail in this post.

This story is also published on Medium.

Why coroutines?

I’m interested in coroutines for the follow benefits:

Event driven asynchronous functions can be written using a control/data flow in a single body of code that can be easy to understand.
Code is portable so that the same code can be tested on development OS and target systems.
Resource efficiency, in terms of memory usage (stack and heap) and CPU cycle usage.

A software timer example

This article will build a simple software timer example. The function has a loop that pauses for several micro seconds before iterating again. While the loop is paused the control flow returns to the caller function.

A simple coroutines task

A simple task periodic is defined in example_simple.cpp. It takes scheduler, period and resume_count as arguments and asynchronously waits period microseconds for 10 iterations, updating the resume_count value each iteration.

The scheduler passed as an argument is not strictly necessary for C++ coroutines, but is used to make the ownership of the context of each task explicit. (It could be possible to use a global scheduler, such as when implementing via OS threads.)

The task returns nop_task. This is a special structure that is linked to the coroutines implementation. In this case a “nop task” refers to a task that does not return a value via co_return.

template<typename SCHEDULER>
nop_task periodic(
    SCHEDULER& scheduler,
    std::chrono::microseconds period,
    volatile uint32_t& resume_count) {
    driver::timer<> mtimer;
    for (auto i = 0; i < 10; i++) {
        co_await scheduled_delay{ scheduler, period };
        *timestamp_resume[resume_count] = mtimer.get_time<driver::timer<>::timer_ticks>().count();
        resume_count = i + 1;
    }
    co_return; // Not strictly needed
}

The function has the following behavior:

Take period as a parameter in microseconds.
Keep track of the number of iteraton via the resume_count counter.
Iterate 10 times.
For each iteration,
- wait period using the co_await keyword.
- then increment resume_count.
Use co_return to exit the coroutines.

The following sequence diagram shows an abstract coroutine execution where an abstracted OS exists to handle the scheduling of process execution. (PlantUML source)

Calling the simple coroutine task

The example_simple() function in example_simple.cpp calls the periodic function once, with 100ms as the period value.

The scheduler_delay<mtimer_clock> is a scheduler class that will manage the software timer to wake each coroutine at the appropriate time, using our RISC-V machine mode timer driver mtimer.

    driver::timer<> mtimer;
    // Class to manage timer coroutines
    scheduler_delay<mtimer_clock> scheduler;
    // Run two concurrent loops. The first loop will run concurrently to the second loop.
    auto t0 = periodic(scheduler, 100ms, resume_simple);

Resuming the coroutine tasks

For this example the scheduler is an object instantiated in the example_simple() function. It needs to be called explicitly to calculate when each coroutine needs to be woken and resumed. This is a convention of the runtime for this example, and not a required convention for C++ coroutines.

The tasks are resumed in the WFI busy loop of example_Simple() when scheduler.update() is called. However, as the scheduler is just a C++ class, this can be called from other locations, such as a timer interrupt handler.

    do {
        // Get a delay to the next coroutines wake up
        schedule_by_delay<mtimer_clock> now;
        auto [pending, next_wake] = scheduler.update(now);
        if (pending) {
            // Next wakeup
            mtimer.set_time_cmp(next_wake->delay());
            // Timer interrupt enable
            riscv::csrs.mstatus.mie.clr();
            riscv::csrs.mie.mti.set();
            // WFI Should be called while interrupts are disabled 
            // to ensure interrupt enable and WFI is atomic.            
            core.wfi();
        ]
    } while(true)

For example as the IRQ handler in this example is a lambda function, we could also capture the scheduler and run the timer coroutine in the IRQ handler.

    static const auto handler = [&](void) {
        ...
        schedule_by_delay<mtimer_clock> now;
        auto [pending, next_wake] = scheduler.update(now);
    };

Building and running with Platform IO

The example can be built and run using Platform IO. The default RISC-V platforms use an old version of GCC that does not support C++20, so a custom virtual platform configured to use xPack 12.2.0-3 riscv-none-elf-gcc and run on QEMU has been created in platformio/platforms/virt_riscv.

build_flags = 
    -std=c++20
    -O2
    -g
    -Wall 
    -ffunction-sections 
    -fcoroutines
    -fno-exceptions 
    -fno-rtti 
    -fno-nonansi-builtins 
    -fno-use-cxa-atexit 
    -fno-threadsafe-statics
    -nostartfiles 
    -Wl,-Map,c-hardware-access-riscv.map

The debug sequence shows entering the function example_simple(), initializing scheduler_delay<mtimer_clock> scheduler; then calling periodic(scheduler, 100ms, resume_simple);.

Once the statement co_await scheduled_delay{ scheduler, period }; is reached the context returns to example_simple(). Then when auto [pending, next_wake] = scheduler.resume(now); is called it returns to the for loop in periodic().

The coroutine handle is stored in the scheduler class by the first call to co_await. The following call to scheduler.resume() looks up the pending coroutine handle and calls resume on the handle.

The stack of the coroutine periodic() before resume can be seen below. It’s called from example_simple().

The stack of the coroutines periodic() after resume can be seen below. It’s called from coroutine_handle::resume, which is called from scheduler_ordered::resume.

The stack of example_simple() function calling resume() is also on the same stack.

Building with CMake and running with Spike

The Makefile has targets to build with CMake.

$ make target
cmake \
        -DCMAKE_TOOLCHAIN_FILE=cmake/riscv.cmake \
        -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
        -B build_target \
        -S .
cmake --build build_target --verbose

The Makefile also has targets to simulate and trace with the standard RISC-V ISA simulator, spike. The forked spike with VCD tracing is used. The forked spike is included in a docker container.

$ make spike_sim
docker run \
        -it \
        --rm \
        -v .:/project \
        fiveembeddev/forked_riscv_spike_dev_env:latest  \
        /opt/riscv-isa-sim/bin/spike \
        --log=spike_sim.log \
        --isa=rv32imac_zicsr \
        -m0x8000000:0x2000,0x80000000:0x4000,0x20010000:0x6a120 \
        --priv=m \
        --pc=0x20010000 \
        --vcd-log=spike_sim.vcd \
        --max-cycles=10000000  \
        --trace-var=timestamp_simple --trace-var=timestamp_resume --trace-var=timestamp_resume_0 --trace-var=timestamp_resume_1 --trace-var=timestamp_resume_2 --trace-var=timestamp_resume_3 --trace-var=timestamp_resume_4 --trace-var=timestamp_resume_5 --trace-var=timestamp_resume_6 --trace-var=timestamp_resume_7 --trace-var=timestamp_resume_8 --trace-var=timestamp_resume_9 --trace-var=resume_simple \
        build_target/src/main.elf
docker run \
     --rm \
    -v .:/project \
     fiveembeddev/riscv_gtkwave_base:latest \
     vcd2fst spike_sim.vcd spike_sim.fst

The results can be viewed with GTKWave. The GTKWave savefile includes address decode and opcode decode by using docker images containing the decoders.

gtkwave spike_sim.fst  spike_sim.gtkw

The benefit of tracing results from the ISA is that it is easy to confirm the periodic timing of the coroutine. (For this example the parameter to periodic() was changed to 1ms).

The periodic write to resume_count and timestamp_resume is traced to VCD so the exact timing of the coroutine execution is visible.

Using GTKWave the context switch can also be examined in detail. In the fake 1GhZ clock used by spike, the context switch takes 104ns.

Coroutine runtime

The runtime is described in detail in this post. The runtime for this example is in the header embeddev_coro.hpp, and it uses the embeddev_riscv.hpp header to provide a simple HAL for RISC-V and host emulation.

Summary

This post describes a simple working example of how to use C++ coroutines in an embedded context. The example and context are not meant to be a realistic use case, but the simplest possible use case that involves and interrupt handler and a context switch.

However, the example can be built on to explore portable and lightweight asynchronous programming techniques. Future posts will look at that topic.

The C++23 standard library provides a limited runtime for coroutines generators. ↩

Update to Docker

2024-06-15T00:00:00+00:00

Docker Images

The reference docker images for building and simulating examples from this blog have been updated:

https://github.com/five-embeddev/build-and-verify/tree/main/docker

Target	Description
riscv-tool-build	Base image for compiling tools
riscv-spike	RISC-V ISA Simulator.
riscv-openocd	OpenOCD JTAG debugger interface
riscv-xpack-gcc	X-PACK packaged GCC
riscv-spike-debug-sim	RISC-V Spike ISA configured to run with OpenOCD
riscv-spike-debug-gdb	RISC-V Spike ISA configured to run with OpenOCD & GDB
riscv-rust	Rust for RISC-V
riscv-gnu-toolchain	Build GCC for RISC-V
riscv-gnu-toolchain-2	Build GCC for RISC-V (using docker compose to conserve resources)

Docker Examples

Examples of usage:

https://github.com/five-embeddev/build-and-verify/tree/main/examples

Example	Description
build-c/	Build a simple C test program for host and target
build-rust/	Build a small rust program
build-run-sim/	Build a full baremetal example and simulate with Spike, debug with GDB
test-code-c/	Small example program

Build with Cmake

e.g. https://github.com/five-embeddev/build-and-verify/tree/main/examples/build-run-sim

docker run \
    --rm \
    -v .:/project \
    -v /home/five/five-embeddev-wsl/build-and-verify/examples/build-run-sim/../test-code-c:/project/test_code \
        fiveembeddev/riscv_xpack_gcc_dev_env:latest \
        cmake \
                -S test_code \
                -B build \
                -G "Unix Makefiles" \
                -DCMAKE_TOOLCHAIN_FILE=../test_code/riscv.cmake
docker run \
    --rm \
    -v .:/project \
    -v /home/five/five-embeddev-wsl/build-and-verify/examples/build-run-sim/../test-code-c:/project/test_code \
        fiveembeddev/riscv_xpack_gcc_dev_env:latest \
                make \
                        VERBOSE=1 \
                        -C build

GTKWave Filters for Debugging VCD Traces of RISC-V Software

2024-04-21T00:00:00+00:00

GTKWave can be used for firmware debugging. This is obviously useful for co-simulation, but is also useful for debugging timing and integration problems.

In a previous post I showed how to create a vcd trace of a firmware run via a fork of the RISC-V ISA simulator.

In this post using https://github.com/five-embeddev/riscv-gtkwave I add:

Instruction Decoding according to the Spike disassembler.
Bus Address decoding according to an elf file.
CSR register decoding.

There are a few methods to decode via GTKWave. The decoders in https://github.com/five-embeddev/riscv-gtkwave are using 3 methods:

Generated Translate filter file.
Translate Filter process.
Signal Grouping and Vector Expansion and Combination

Generated Translate Filter File.

The generate_csrs.py script uses pyvcd to generate enumeration files such as mcause.exception_code.gtkw from YAML CSR data csr.yaml.

Filter Process

RISC-V ISA Disassembly for GTKWave

The decode_inst program uses the disassembler defined by the RISC-V ISA Simulator in disasm.h to disassemble instruction words.

It also uses isa_parser to determine the ISA to dissassemble. The filename determines the ISA (via argv[0], e.g. decode_inst-rv32ic or decode_inst-rv64g.

e.g. the opcodes.hex file:

20010ae2
20010ae6
20010ae8
20010aea
20010aee
20010af0
20010af2
20010af4
20010af6
20010afa

Piped into decode_inst gives the following result.

$ cat opcodes.hex | ./decode_inst 
auipc   t0, 0x0
c.add   a3, t0
c.mv    t0, ra
jalr    ra, a3, -88
c.mv    ra, t0
c.addi  a5, -16
c.sub   a4, a5
c.add   a2, a5
bgeu    t1, a2, pc - 120
c.j     pc - 152

ELF Symbol Lookup for GTKWave

The decode_addr program converts hex address values to symbols names. It uses the global variable symbols or function symbols.

It is derived from elfloader.cc in the RISC-V ISA simulator.

As GTKWave cannot pass command line arguments DECODE_ELF must be set as an environment variable with the path to the ELF file to use.

$ cd src/
$ DECODE_ELF=../example/main.elf ./decode_addr
0
-
0000
-
0000000020010000
_enter
0000000080000008
mti_count

Signal Grouping and Vector Expansion and Combination

Registers signal vectors are expanded into bits, and fields combined as groups of bits.

The pyvcd class GTKWSave provides trace_bits for this. However it only provides a single bit function trace_bit.

The generate_csrs.py script subclasses GTKWSave and adds trace_bit_group for multibit fields. These can be interpreted via translate filter files.

Added trace_bit_group:

class UpdateGTKWSave(vcd.gtkw.GTKWSave):
    def trace_bit_group(
        self,
        lsb: int, msb: int,
        name: str,
        alias: str,
        color: Optional[Union[vcd.gtkw.GTKWColor, str, int]] = None,
        translate_filter_file: Optional[str] = None,
    ) -> None:

Iterate over fields in a register and add the trace_bit or trace_bit_group. There is one save file per CSR.

   gtkw = UpdateGTKWSave(rout)
   gtkw.comment(f"Fields for register {reg_name}")
   gtkw.begin_group(reg_name)
   with gtkw.trace_bits(reg_path):
       for fkey, fdata in reg_data['fields'].items():
           gtkw.comment(f"Field {reg_name}_{fkey}")
           fwidth=get_field_width(fdata)
           msb,lsb=get_field_range(fdata)
           if fwidth==1:
               gtkw.trace_bit(reg_width-lsb-1, 
                   name=f"{reg_path}",
                   alias=f"{reg_name}_{fkey}")
           else:
               translate_filter_file=...
               gtkw.trace_bit_group(
                   reg_width-msb-1, 
                   reg_width-lsb, 
                   name=f"{reg_path}",
                   alias=f"{reg_name}_{fkey}",
                   translate_filter_file=translate_filter_file)
   gtkw.end_group(reg_name)

Firmware Trace Example

TODO

There are many limitations to these programs.

64bit/32bit distinctions are not

In a real world application other decoders that are useful are:

MMIO Peripheral register decoding.
External bus/device (I2C/SPI) register decoding.
RTOS/OS instrumentation (e.g. current task, current memory map etc)
Test name/assertion name.
etc.

RISC-V ISA Instruction Quick Reference Update

2024-03-03T00:00:00+00:00

The Instructions Quickref has been updated to match the changes made for Compiler Explorer.

The opcode references are generated from opcodes.yaml which is generated by convert_opcodes.rb in https://github.com/five-embeddev/riscv-docs-html/tree/gh_pages.

RISC-V ISA Reference for Compiler Explorer

2023-11-15T00:00:00+00:00

Compiler explorer now includes RISC-V opcode references for the rv64 targets, following my pull pull request and initial work by Siyao.

The updated files are:

etc/scripts/docenizers/docenizer-riscv64.py: Generator, converts yaml to ts.
lib/asm-docs/generated/asm-docs-riscv64.ts: The generated opcode documentation.

The opcode references are generated from opcodes.yaml which is generated by convert_opcodes.rb in https://github.com/five-embeddev/riscv-docs-html/tree/gh_pages.

The opcode decriptions are automatically extracted from the ISA user manual in HTML format. For example the description for sd is extracted from the Load and Store Instructions section.

To generate the data run these commands in the compiler explorer repo:

 cd compiler-explorer/etc/scripts/docenizers/
./docenizer-riscv64.py \
    -i https://five-embeddev.github.io/riscv-docs-html/opcodes.yaml \
    -o ../../../lib/asm-docs/generated/asm-docs-riscv64.ts

RISC-V ISA Manuals to HTML

2023-07-31T00:00:00+00:00

The User ISA and Privileged ISA have been are converted to HTML from TEX on the upstream repo.

The latest upstream versions have recently been converted to asciidoc, but the legacy versions that were used to generate HTML on this site are converted from the older TEX.

In theory converting tex should be as simple as running a conversion tool such as pandoc or latex2html but without some optimization that gives quite ugly results - in particular for tables and diagrams.

The set of scripts that this blog uses to optimize the pandoc output has been uploaded to https://github.com/five-embeddev/riscv-docs-html. A Dockerfile is used to configure a build environment with pandoc and asciidoctor and the other tools used to do the conversion.

A set of static html github pages have been exported here, https://five-embeddev.github.io/riscv-docs-html/. They HTML is identical, but it lacks the side navigation menu and css style used by this site.

These scripts are also used to create the opcodes.yaml and csr.yaml data files used by the Instruction Quick Reference and CSR Quick Reference on this site.

RISC-V Interrupts/Exceptions Quick Reference

2023-05-11T00:00:00+00:00

A fix has been made to the Interrupts/Exceptions Quick Reference to clarify that mstatus.mpp is set to the the least-privileged supported mode on mret. The local version of Machine-Level ISA has been updated to the Priv-v1.12 source as this is the current version on https://riscv.org/technical/specifications/. References to the depreciated user mode interrupts and the n extension were also removed.

From mstatus:

An MRET or SRET instruction is used to return from a trap in M-mode or S-mode respectively. When executing an xRET instruction, supposing xPP holds the value y, xIE is set to xPIE; the privilege mode is changed to y; xPIE is set to 1; and xPP is set to the least-privileged supported mode (U if U-mode is implemented, else M). If xPP≠M, xRET also sets MPRV=0.

From sstatus:

When an SRET instruction (see Section [otherpriv]) is executed to return from the trap handler, the privilege level is set to user mode if the SPP bit is 0, or supervisor mode if the SPP bit is 1; SPP is then set to 0. 11

CSR Quick Reference Update

2023-05-04T00:00:00+00:00

The CSR quick reference list was updated:

Cross references to manuals.
Details for some fields.

RISC-V ISA Manual Update

2023-05-03T00:00:00+00:00

The User ISA and Privileged ISA have been updated to tag Priv-1.12 in the upstream repo and re-generated as HTML.

Updated to official release branch (Priv-1.12)
Added links to source documents, source version.

The upstream changelog from git is:

bump priv version
Relax Svpbmt sequence slightly
Add FLH, FSH to defined transformed instructions for H extension (#792)
priv spec version 20211202
boldface ratified extensions
Clarify that henvcfg.PBMTE is read-only zero if Svpbmt is not implemented
Clarify that PBMTE is read-only zero if Svpbmt is not implemented
fix typo
Permit speculative execution of HLV/HSV; reset hgatp.MODE, satp.MODE
Fix Travis build status image URL
Rework the description of exceptions for Svinval (#786)
Change H extension to version 1.0 (#787)
Interrupts and exceptions are different things. (#788)
Priv specs are ratified
Add menvcfg.PBMTE / henvcfg.PBMTE
Remark that Svnapot and Svpbmt require Sv39
Move SFENCE.VMA/satp.MODE remark to better location
Clarify that implicit reads of CSRs return same value as explicit reads (#783)
Fix typo
Add VS field
Split RV32 [v]sstatus figures into two rows
Add Hazard3 to open-source marchid list (#784)
Fix typo
Specify a sequence to regain coherence wrt. mismatched PBMTs
Avoid use of “timebase”
Clarify definition of [m]time CSR
Merge branch ‘jhauser-us-jhauser-2021-CSRFieldMods’
Clarify when SFENCE.VMA/HFENCE.GVMA need be executed
Extension is “implemented”, not “enabled” (in Svinval) (#780)
Explain why mstatus.TVM doesn’t affect vsatp, HFENCE.VVMA (#779)
H extension requires page-based address translation (#778)
Non-normatively remark that high-order PPN bits aren’t ignored
Revert “Separate transformation for HLV instructions (#777)”
Fix typo
Separate transformation for HLV instructions (#777)
Memory access traps may write zero to stval (#776)
Accesses to pages with mismatched attrs are I/O and memory wrt FENCE (#774)
Rename hstatus.HU (#770)
Allow more bits of hideleg to be writable (#772)
Clarify condition when virtual instruction trap will occur (#773)
CSR mideleg masks hideleg, hip, and hie (#771)
Rewrite most instances of “hardwire” as “read-only” (#768)
Remove trailing whitespace from a.tex (#767)
Document version 20211105-signoff
Further relax PMP/address-translation caching interactions
Merge pull request #763 from riscv/virt-mem-extensions
Add Sv57 and Sv57x4
Merge branch ‘master’ of github.com:riscv/riscv-isa-manual
Back to draft status
Define the Zicntr and Zihpm extensions
Improve text in Zicntr section
Document version 20211028-signoff
Incorporate Steve’s feedback
No valid LR/SC reservation upon reset
Fix editing error in mtval/stval definition
Clarify order in which PMP CSRs must be implemented
Fix permissions of *envcfg CSRs
Improve description of FENCE.TSO
Add example to clarify mip.SEIP behavior
Bump priv version number
Priv-1.12 spec for public review
JohnH is an editor of the priv spec
RISC-V Foundation -> RISC-V International
Freeze the hypervisor extension, version 1.0.0-rc (#739)
mip.MSIP and mie.MSIE may be hardwired zeros (#738)
Hypervisor extension requires page-based address translation (#737)
Fix apparent typo re hpmcounter*h (#735)
State behavior of uncacheable accesses to cacheable locations
Clarify that WARL fields contain legal values after reset (#734)
Rename STCE to STCD to reverse its polarity
Generalize SSIP to support forthcoming interrupt controllers (#726)
Speculative implicit reads, v2 (#724)
Fix a typo in Figure A.13. (#733)
Merge pull request #727 from riscv/mseccfg
Make virtual instruction exceptions more consistent for VU mode (#730)
Pedantically clarify behavior of writing lo/hi parts of counters
Remove errant preface entry
Clarify widths of privileged CSRs (#728)
Revert “Replace “EEI” with “execution environment” (#723)”
Add preface entry
Designate some of SYSTEM opcode for custom use
Add mconfigptr CSR (#697)
Replace “EEI” with “execution environment” (#723)
Fix (again) non-normative CSR side-effect text
Remove historical remark on MRET definition
Fix non-normative text about CSR ordering (#720)
Add marchid for Hummingbirdv2 E203 (#664)
Update H chapter table of synchronous exception priorities (#717)
Tweak table of synchronous exception priorities (#716)
Make explicit the priorities of synch. exceptions of H extension (#711)
Clarify priorities of synchronous exceptions (#715)
stval already cannot be zero on breakpoints, misaligned addresses (#714)
VS mode should not see exception code 10 (#712)
Merge branch ‘jhauser-us-jhauser-2021-HBaseI’
Corrections to mstatus in hypervisor chapter (#710)
Minor improvements to text for virtual instruction exceptions (#709)
Clarify when mstatus.FS may be hardwired zero (#707)
Interrupt conditions are also evaluated on falling edges
Generalize interrupt trap condition evaluation conditions (#705)
Clarify that RV64 accesses to mtime[cmp] are atomic
State that misa.F does not affect mstatus.FS
Improve rules for virtual instruction exceptions, again (#703)
Clarify mepc invalid address conversion
Improve description of interrupt traps (#701)
Merge branch ‘jhauser-us-jhauser-2021-extStats’
Clarify that SFENCE.VMA isn’t required for Sbare
Fix b6cade07034d39e65134a879a5c3369d50e0df0e
Remove N extension chapter for now
CSR instead of field (#669)
Add non-normative text about VIPT caches not being exposed
Remove concept of hard reset from normative text
Add marchid for XiangShan (#661)
PMP RWX are collectively WARL, with R=0 W=1 being illegal (#658)
Delete detailed text surrounding RVC immediates
Merge branch ‘jscheid-ventana-jscheid/c-pmas’
Merge pull request #655 from riscv/remove-l-t
Clarifying FENCE operation behavior for external devices. (#657)
Merge pull request #652 from rafaelcalcada/master
Use plural “base ISAs” rather than “base ISA” when appropriate
Fix capitalization of HINTs
Fix hyphenation
Clarify need for HFENCE.GVMA after hgatp.MODE change
Assin version number 0.1 to Zmmul
Merge pull request #648 from riscv/zmmul
Merge pull request #645 from riscv/listofitems
Merge pull request #644 from EwoutH/patch-1
marchid request for RudolV (#643)
Minor mstatus and sstatus layout edits. (#642)
SUM should be hardwired to 0 for cores without paging (#641)
Requesting marchid for cv32e40x and cv32e40s (#630)
marchid request for Ibex (#638)
Define canonical location of K extension in ISA string
Clarify hypervisor privilege hierarchy/global interrupt enables
Add FENCE.TSO and PAUSE to RV32I instruction table
Clarify that AMOs use the original address when rd == rs1 (#632)
fix typo in preface
s/NSE/Custom/ in RVC spec
wrap long line
Merge pull request #398 from riscv/pause
Update preface
Clarify type of timer interrupt (#617)
Fix editing error introduced in 9ff515cd6695ac392e5ca32b73a135aa197e2778
Delete duplicate (and now inconsistent) version number given in body text. Closes #618.
Revert “should -> shall in definition of 0 instruction”
should -> shall in definition of 0 instruction
Explain rationale for seting xPP=U on an xRET
Add preface note that N extension was moved to its own chapter
Clean up NMI/mepc wording
Additional FS clarification
Clarify rm field on widening conversions (#619)
spell check
clarify that FS need only be set to dirty if the state is actually changed
LR/SC extension commentary tweak
Clarify when FP conversions raise the Inexact flag
Use consistent wording for FP exception text
Make unused misa fields 0 (WARL) rather than WLRL. (#615)
Dedicated section for machine-level memory-mapped registers (not standard CSRs) (#614)
Clarify G bits in all G-stage PTEs are reserved (#613)
PMP uses physical addresses (not effective addresses) (#610)
Update editors
Update contributors
mcounteren is WARL
PMP TOR clarifications
Another attempt to clarify SEIP RMW semantics
Attempt to clarify SEIP RMW semantics
fm=0 for FENCE HINTs
Both HWBPs and EBREAKs populate mtval (#601)
marchid request for NEORV32 core (#579)