riscv/riscv-platform-specs

RISC-V Profiles and Platform Specification

RISC-V Platform Specification

The files in this project are used to create the RISC-V Platform Specification. This specification defines the set of firmware and hardware required of a RISC-V platform so that it may install and run various operating systems.

The content of the specification is created and controlled by the RISC-V Platform Horizontal Subcommittee (RISC-V Platform HSC). Information about the subcommittee can be found at https://lists.riscv.org/g/tech-unixplatformspec. Please note that membership in RISC-V International is required to post to the mailing list, but it is publicly readable. Membership in RISC-V International is free for individual community members.

All discussion of this specification occurs on the task group mailing list. Please use github issues for bug reports.

Licensing

The files in this repository are licensed under the Creative Commons Attribution 4.0 International License (CC-BY 4.0). The full license text is available at https://creativecommons.org/licenses/by/4.0/.

Repository Content

• Makefile => 'make' in this directory will produce the HTML, markdown, and PDF versions of the current spec
• README.md => this file
• riscv-platform-spec.adoc => the spec in asciidoc format; there are several subsidiary asciidoc files that get included by this file.
• docs-resources => Git Submodule with the RISC-V documentation theme, fonts, etc. for building the document

Repository Branches

• All development occurs on main; no content on main is to be considered TSC-approved content.
• TSC-approved content will be clearly marked as such.

Dependencies

The PDF built in this project uses AsciiDoctor (Ruby). For more information on AsciiDoctor, specification guidelines, or building locally, see the RISC-V Documentation Developer Guide.

Cloning the project

This project uses GitHub Submodules to include the RISC-V docs-resources project to achieve a common look and feel.

When cloning this repository for the first time, you must either use git clone --recurse-submodules or execute git submodule init and git submodule update after the clone to populate the docs-resources directory. Failure to clone the submodule, will result in the PDF build fail with an error message like the following:

$ make
asciidoctor-pdf \
-a toc \
-a compress \
-a pdf-style=docs-resources/themes/riscv-pdf.yml \
-a pdf-fontsdir=docs-resources/fonts \
--failure-level=ERROR \
-o profiles.pdf profiles.adoc
asciidoctor: ERROR: could not locate or load the built-in pdf theme `docs-resources/themes/riscv-pdf.yml'; reverting to default theme
No such file or directory - notoserif-regular-subset.ttf not found in docs-resources/fonts
  Use --trace for backtrace
make: *** [Makefile:7: profiles.pdf] Error 1

riscv-platform-specs's Issues

both CLIC and CLINT seems to be used for the same thing

Two abbreviations seem to be used for "Core-Local Interrupt Controller"

CLINT is the only one mentioned in the Terminology table at the top here: https://github.com/riscv/riscv-platform-specs/blob/main/riscv-platform-spec.adoc#terminology

The specifications linked are:

• CLIC: https://github.com/riscv/riscv-fast-interrupt/blob/master/clic.adoc
• ACLINT: https://github.com/riscv/riscv-aclint/releases/download/v1.0-draft2/riscv-aclint-1.0-draft2.pdf

Can/Should this be made more cohesive? CLIC seems more in line with PLIC.

Hypervisor guard hole

The current platform spec says that...

On RV64I-based Unix-class systems the negative virtual addresses are reserved for the kernel.

However, at least on x86_64 the memory map includes a "guard hole" reserved for the hypervisor. Is there intended to be a similar cutout in riscv, and if so should that be indicated here?

Future interrupt controller of M platform

In interrupt controller section of M platform, embedded systems are recommended to use PLIC, CLIC, or both as interrupt controller(s). However, APLIC have smaller memory map requirement than PLIC. Thus, I thought that APLIC is more suitable in embedded systems and may become an option for future interrupt controller of M platform.

PCI ECAM requirements

ECAM must be preserved in the face of OS re-enumeration of the PCI fabric. It should be noted that an OS/other SEE software may renumber downstream buses. When this happens, in an implementation composed from multiple independent root ports, it is necessary to ensure that the correct underlying fabric routing is preserved.

Missing LICENSE file

While the README file references the project is licensed under the CC-BY-4.0 license and provides a link to the full license text. the lack of a LICENSE file prevent GitHub from recognizing the license.

I propose adding a plain text LICENSE file like the one used in the ISA manual.

I'm happy to add this into the project directly and will do so shortly. If anyone has concerns, please raise them.

Thanks,
-Jeff

Adopt the RISC-V documentation format

This is a 3-step update for which I will be submitting a PR:

1. Import of docs-resources project as a submodule.
2. Updates to the Makefile to use more options on asciidoctor PDF build, including the RISC-V theme (.yml file) and the fonts directory.
3. Updates to the main .adoc file to include more variables for the build and the logo for the title page

Once complete, the side-effect for anyone starting to use this repo locally will be that they'll need to learn to use Git Submodules. Plenty of useful information is here. But the key step is to issue a git submodule update --init after a new clone or the first pull after this PR.

At key points in the future, we may want to use the git submodule update to update to a new level because Submodules always "link" at a given commit level. (More discussion here as we work with this.)

If anyone has questions about the process, please free to let me know.

relax "If Hypervisor extension is supported then the misa.H bit must be writable."

misa
If H extension is supported then the H bit must be writable.

For example, open-source Rocket-chip does not (yet): chipsalliance/rocket-chip#2841

Unnecessary/Inappropriate documentation of kernel address space decisions

Currently the supervisor spec says:

On RV64I-based Unix-class systems the negative virtual addresses are reserved for the kernel.

Why is this part of the platform spec? What addresses are used by the kernel and what addresses are used by userspace are entirely up to the kernel and not the concern of the platform, so unless I'm missing something it does not make sense to specify arbitrary implementation details.

Eventual completion for vacant memory

The privileged spec describes that PMAs may be vacant. The current specifications are vague around handling of unpopulated (aka "vacant") memory. They must mandate a behavior, e.g. all zeros/all ones/error response

Server: System Date/Time: Improve explanation for GetTime()

In section 2.2.7.2 of the Server profile, "System Date/Time", the explanation for GetTime() sounds awkward:

"Must be implemented by firmware" is clear, but what is "to incorporate with the underlying system date/time mechanism" supposed to mean?

Not being a native speaker, I believe correct verb usage is to incorporate sth., not to incorporate with sth.

I am guessing what it really means is to expose the underlying system date/time mechanism?

Inconsistent mtime requirements

Currently the spec says:

• Platforms are required to provide an at least 10ns resolution 64-bit counter with strictly monotonic updates.

• The hardware clock that drives the counter is required to operate at a minimum frequency of 10MHz.

but also:

For a counter with 10ns resolution the timebase-frequency value would be 100000000 (100 MHz) which would also be the minimum possible value for timebase-frequency. From the software perspective a unit increment of the mtime value would correspond to a 10ns interval. However the hardware clock driving the counter could operate at a lower frequency, thereby incrementing the mtime value by more than one unit per clock tick.

These are all contradictory; a 10MHz clock doesn't give a resolution of 10ns, and similarly if the clock is at a lower frequency than timebase-frequency, with the latter still reporting 100 MHz, and steps multiple values at a time then you're not going to have a resolution of 10ns since you never see an individual step.

How to handle non-coherent I/O masters

Currently the base spec says:

Memory accesses by I/O masters can be coherent or non-coherent with respect to all hart-related caches.

However, nothing is said about what software should do in that case. I believe the CMOs extension should be required in such a case, as otherwise software cannot work without adding SoC-specific cache management operations, which quickly becomes the kind of mess that platform specs are supposed to stop happening.

PCI cache coherency

Section 4.7.3.4 describes behavior for No_Snoop bit but does not prescribe DMA coherence as a requirement. It shoud.

Specify word-size accesses to UART registers

The "UART/Serial Console" section does not say what size memory accesses are required to work for UART registers. I recommend that support be required only for word-size (4-byte) accesses, and that other sizes may possibly fail with an access fault or bus error.

The AMBA Advanced Peripheral Bus (APB) does not support reads narrower than word-size, and before 2010 did not support writes narrower than word-size either. If we say that byte-size and/or halfword-size accesses must be supported, then it's debatable whether a UART connected through even a recent APB can actually conform. In any event, there may be other buses in use, standard or custom, that can perform only word-size accesses, like older APBs.

Word-size accesses are obviously sufficient for interacting with the UART, so I can see no reason for the platform spec to require that other access sizes be supported.

A question about self/cross-modifying code (SMC/CMC)

Hi team,

I am looking into some descriptions in RISC-V of self/cross-modifying code (SMC/CMC), which is (quoted from intel x86 manual vol 3A, 8.1.3 "Handling Self- and Cross-Modifying Code")

The act of a processor writing data into a currently executing code segment with the intent of executing that data as code is called self-modifying code.
...
The act of one processor writing data into the currently executing code segment of a second processor with the intent of having the second processor execute that data as code is called cross-modifying code.

Software with just-in-time compilers relies on such behaviors heavily, such as OpenJDK [1].

The current RISC-V port of OpenJDK (ported from its AArch64 port) also uses such techniques. Some instructions (nop, jal) running on some reader harts may get dynamically patched by other writer harts (Of course on Linux there is __riscv_flush_icache called after the CMC writing behavior). But it's unknown to me if the readers can observe a legal state, so I am searching if there are documents setting this patching behavior as legal, that is, patching these instructions would not make some reader harts observe an "undefined behavior".

I didn't see much in the riscv-spec so I went to our riscv-isa-manual github. Coming from the nearly same issue and its comment [2], I reached here, with finding [3]. I think it can reflect what I am searching for (it doesn't say the store operation rise up exceptions and clarifies the legality of the read is guaranteed to be in a clear state, without undefined behaviors, so I guess it might be an intel x86 alike statement as below that all instructions at runtime could be safely patched when they are properly aligned).

I can find statements from the arm-v8 manual that only nop, bl, b, isb alike several instructions could be safely cross-modified. No safety of cross-modifying other instructions is guaranteed, described in "B2.2.5 Concurrent modification and execution of instructions".

In [3] I found our statement got an update to To order older stores before younger instruction fetches, .... I don't know if the older stores description could implicitly reflect whether RISC-V supports the CMC/SMC behaviors. I am a little confused about this.

The question is simple: is it legal to execute SMC/CMC behaviors on any instruction, that no interesting unpredictable state could be observed, in RISC-V's spec for now?

Thank you in advance!

Best,
Xiaolin

[1] http://cr.openjdk.java.net/~jrose/jvm/hotspot-cmc.html
[2] riscv/riscv-isa-manual#650 (comment)
[3] 38d0b4b#diff-e2e67320afc3dbcf884d10778f562bfa141048bbccbf7be067df8813a55a66fdL131-L137

CLIC requires original basic interrupt mode

The M platform description says that, to say CLIC is implemented, the original basic interrupt mechanisms must also be supported. That seems wrong - especially when the CLIC spec provides for the original basic mechanism not to be supported.

I/O ordering requirements (for non-PCIe devices)

The OS-A platform spec used to have a requirement for strong point-to-point I/O ordering for most devices. It was deleted last year with the remark "All the points specified in supervisor.adoc are already described in the new revamped platform spec", but I cannot find any statement to this effect. The change was here: 3e12ad1#diff-1d563824326d2cf24a223ae5c45f6247f5fd9a553acff627370ddd8f9e64b031L16-L17

I think we just need to add the following clause: "Unless otherwise specified by a given I/O device, I/O devices are on ordering channel 0 (i.e., they are point-to-point strongly ordered)."

I see that there are now some different requirements for PCIe. That's OK; these statements don't conflict, because of the "unless otherwise specified" phrase.

relax RAS precise exception on uncorrectable data

The platform spec includes this proposed requirement:

Attempted use of corrupted (uncorrectable) data must result in a precise exception on that instruction with a distinguishing custom exception cause code.

This adds a non-trivial performance/area cost, and is a stronger requirement than other contemporary ISAs and system architectures.

Virtual timers require an offset value

Current Sstc extension does not seem to include a virtual timer offset. This will require clarification.

RVM platform requirements

Great initiative!
I do however have questions about the requirements for the RVM platform, specifically the 32-bit version;

Is it realistic to require RV32G in order to comply with the RVM platform? It seems like a more natural choice would be RV32IMAF, as RV32D is pretty heavy on the floating-point for small microcontrollers (most Cortex-M devices don't even have double precision support in hardware, that's only available in the M55 and M7).

Also the C extension would make sense to include as embedded applications are quite sensitive to code size, but that's probably a different discussion worthy of its own issue...