riscv-non-isa/riscv-brs

The Boot and Runtime Services (BRS) specification provides the software requirements for system vendors and Operating System Vendors (OSVs) to interoperate with one another by providing expectations for the Operating System (OS) to utilize in acts of device discovery, system management, and other rich operations provided in this specification.

RISC-V Boot and Runtime Services (BRS) Specification

The Boot and Runtime Services (BRS) specification provides the software requirements for system vendors and Operating System Vendors (OSVs) to interoperate with one another by providing expectations for the Operating System (OS) to utilize in acts of device discovery, system management, and other rich operations provided in this specification.

This specification is still a work in progress, based on an earlier draft available at https://docs.google.com/document/d/1X0TSbheEJjRGWhG2nzUnfIl_QcHWSuvd

License

This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). See the LICENSE file for details.

Contributors

Contributors to this specification are contained in the contributors.adoc file.

Dependencies

This project is built using AsciiDoctor (Ruby). The repository has been setup to build the PDF on checkin using GitHub actions. Workflow dependencies are located in the dependencies directory.

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

Building the document

The final specification form of PDF can be generated using the make command.

riscv-brs's Issues

Dependency: ACPI 6.6: APEI

Does anything RISC-V specific need to be added to e.g. GHESv2 or elsewhere.

Security Requirements - Reference Security model spec

@rsahita had some thoughts he'd help with identifying things to reference in security model spec from BRS spec. While the security model spec isn't ratified, it'd be good to provide pointers in the spec for guidance purposes.

Definition and usage of the term "system" is confusing and inconsistent

The two sentences of the glossary definition for system directly
contradict each other. The first sentence says a system is both a
platform and software; the second sentence contradictingly
says it is both of those things but also only one of those things.

Elsewhere in the document, system, when used independent of
compound terms (i.e., not "operating system", etc.) frequently refers
to only that which implements the BRS and not, for example, an
operating system or user application.

I would suggest completely replacing use of the term system with more
specific and appropriate terms, but I do understand this approach may
not preferred by others.

SMBIOS specification points to https://github.com/riscv/riscv-smbios

The SMBIOS 3.7 specification points to https://github.com/riscv/riscv-smbios.

Can we change the README of the repository to point clearly to the new site?

We should also change the status of the old repo to sunsetted.

Dependency: SBI: CPPC Extension

Note this as an SBI requirement in the doc.

Depend on the PRS proposal.

Dependency: ACPI 6.6: 3.11.3.1. (Supported Platforms) section doesn't call out interrupt-signaled events as a choice for hw-reduced operation

https://mantis.uefi.org/mantis/view.php?id=2377

Reading 3.11 may give the impression that that for reduced-HW operation, GPIO-signaled ACPI Events is the only mechanism to replaced fixed hardware interface events. In fact, both GPIO-signaled and Interrupt-signaled ACPI events are viable choices and the table in 3.11.3.1 ought to be updated to reference section 5.6.9 as well.

Today calling out GPIO and Interrupt-signaled events as valid implementation choices is done by the Arm BBR spec and the WIP RISC-V Booting and Runtime Services spec, but it really belongs in the ACPI spec itself.

SMBIOS type 44 is not possible without SMBIOS type 4

Currently in smbios.adoc type 44 is required while type 4 is not even mentioned.

Type 44 is meant to extend the information in type 4. Field Referenced Handle must refer to the corresponding type 4 structure. So if type 44 is required type 4 must be required too.

smbios.adoc describes a field hart ID. This requires one Processor-Specific Data structure per hart. It remains unclear if one type 44 structure should be created per hart or if there shall be one type 44 structure per processor and an array of Processor-Specific Data structures relating to this processor.

Do we need one type 4 structure per hart, or one per processor?
Do we need one type 44 structure per hart, or one per processor?

harts: mandate _LPI objects

Define BRS-S as a superset of BRS-I

It's not inconceivable that server fw implementations may have a few additional requirements on top of the regular BRS-I ones.

Note regarding calling conventions is either redundant or incomplete

The Hart Requirements section contains a note regarding UEFI calling conventions. This is unnecessary and redundant, as the calling conventions for UEFI are obviously described in the UEFI specification, and also not a requirement on the hart.

However, if it is important for some reason to repeat this information for the reader, it is not clear why this is only done for UEFI and not for other calling conventions (i.e., SBI).

Confusing: The primary booting hart must bring all the secondary non-booting harts online by invoking sbi_hsm_hart_start one by one.

riscv-brs/secondary.adoc

Line 4 in bd40345

primary booting hart must bring all the secondary non-booting harts online by

The sentence makes it sound like a BRS-compliant firmware implementation must bring all secondaries online, which is not true.

List the required UEFI boot and runtime services as well as protocols

Hi @andreiw, @adurbin-rivos,

Shall we add a section to clearly list all the required and recommended UEFI boot and runtime services as well as related protocols?
With that, users can easily get a checklist when implementing their own FW.

Regards,
Haibo

Dependency: ACPI 6.6: MADT AIA / PLIC entries

Remove Background Section

We have a placeholder for Background, but there's no content. Remove it; we can bring it back, if necessary.

Dependency: ACPI 6.6: PPTT

Is PPTT as-is a good fit for RISC-V or does it need to evolve?

Use must, should, may terminology along with IDs for each requirement

In the BRS meeting, it was indicated we should use the terms 'must, should, may'. https://github.com/riscv-non-isa/server-soc has usage like that. Additionally, each requirement in that spec has an ID that can be referenced. We should adopt a similar scheme. Ved (@ved-rivos ), do you have specific pointers on the language and asciidoc recipes that help aid this?

Dependency: UEFI RISC-V binding

https://bugzilla.tianocore.org/show_bug.cgi?id=4232

Error handling (kernel vs firmware first)

Current language for BRS-I mentions firmware-first (APEI) handling. We need to close on whether that's really doable for v1 of the BRS or whether we should just remove any requirement on error handling implementation for now.

Cross-check security requirements with other industry initiatives (Arm BBRS)

Do we consider these part of the BRS-I or should this be a separate document like BBRS?

Dependency: TCG ACPI spec work

Enhance TPM2 with start method for SBI ecall to support fTPM.

Dependency: SPCR spec work

This tracks the SPCR improvement dependency (min: SBI console support).

Is there any requirement in the BRS specification regarding the version of UEFI implementation?

From the Bibliography, refence to uefi2.11, (Only find 2.10 in uefi.org).
[7] “Unified Extensible Firmware Interface Specification 2.11.” [Online]. Available: uefi.org/
specifications.
Does the BRS have a minimum requirement for the UEFI version in firmware implementation?

Do we need a LinuxBoot recipe?

Comments on the Illustrative doc:

• The ARM LBBR-v1 profile doesn't appear to mandate any UEFI boot services. Should we mandate all of these for all OS-A SEE profiles?
• This [UEFI runtime services section] is a longer list than what the ARM LBBR-v1 profile requires. Do all of these UEFI services need to be mandated for all SEE-A profiles?
• Where do LinuxBoot requirements fit in? If BRS-I, the regular server class requirements do not hold good. Should it be separate recipe itself like ARM did?

I could see LinuxBoot to be a case of BRS-B (what is called VI here). If folks disagree because that's too open-ended, we can add a separate recipe

Add a section for definition of terms

Similar to https://uefi.org/specs/ACPI/6.5/02_Definition_of_Terms.html

Would help keep the rest of the document concise.

File DMTF issue to update Type 44 content for RISCV SMBIOS

          Looks good to me. Thanks a lot for taking care of this.

Now, this spec being moved to BRS, an ECR to SMBIOS spec required to update the link it is pointing for table 44?

Originally posted by @vlsunil in #90 (review)

ACPI/FFH gaps around exposing suspend-to-RAM capability.

          We discussed this topic in BRS meeing today: https://docs.google.com/presentation/d/1bWS_YUZAZwwDDgHOWf2S1vyoP_Eh7y6090-NjoJQTSo/edit#slide=id.g21d5651495d_0_17

Suspend shouldn't be mandatory, but we don't have the ACPI framework in place to allow arbitrary sbi calls?

Originally posted by @adurbin-rivos in #52 (comment)

Dependency: ACPI: Define _CCA behavior for RISC-V

Recommend this as ASWG change to mandate _CCA on any RISC-V platform or force a specific meaning when _CCA is not present.

Place some conditionality on SBI PMU Extension requirement

Current text indicates PMU is mandatory, but that requirement is actually dependent on some in-flight extensions. We should capture our reasoning in the text and make a late binding decisions based on the dependent extensions being ratified.

Atish (@atishp04 ), you said you'd pick this one up.

smbios section: put into table format

The current smbios section enumerates the different tables into mandatory, etc. However, each one is an asciidoc section. We should convert these into a table format.

How to collect SMBIOS type 44 information

Firmware typically only runs on a single hart. The SBI Hart State Management extension was introduced to allow running on a single hart and let the OS wake up all other harts.

On a system with socketed CPUs the only way to determine the information in the SMBIOS type 44 table would be to wake up each hart and call the SBI Base Extension to read mvendid, marchid, mimpid for the respective hart. This would unnecessarily waste boot time.

In a system with hot plugable CPUS the content of the table will be of no value because it may not represent the current state.

The smbios information is not only inaccurate it is also redundant as /proc/cpuinfo already provides it. We should neither require nor suggest providing this table.

Dependency: ACPI 6.6: RHCT

The relationship between recipes and sections is not clear

Recipes should be composed of sections in the BRS, not external
specifications. The current section organization is confusing with
respect to what is and is not a requirement for a particular recipe.
For example, the ACPI section refers to many requirements as
mandatory, but the intention is that entire section is ignored (i.e.,
not mandatory) if not called for in a recipe, such as BRS-B, where
ACPI is intended to be optional.

Confusing: "The secondary cores must boot in an ordered fashion using SBI HSM extension"

riscv-brs/secondary.adoc

Line 3 in bd40345

The secondary cores must boot in an ordered fashion using SBI HSM extension. The

Not sure what is meant here by "ordered fashion". sbi_hsm_hart_start takes a hart id, and the order sbi_hsm_hart_start is called on secondary hartids is OS defined.

Blocking Dependency: RISCV-SMBIOS spec not ratified

https://github.com/riscv/riscv-smbios/blob/main/riscv-smbios.adoc

Confusing language around SUSP and reset

riscv-brs/sbi.adoc

Line 21 in 8318e6b

** The supervisor operating system should preferably use UEFI interfaces for system

SUSP has no UEFI RT equivalent, so it doesn't make sense to guide readers to prefer a UEFI interface here. Larger question is why is it being mandated? I can imagine devices where suspend-to-ram is not a product requirement.

I think we talked about mandating SRST, so I don't want to revisit that, but it is a requirement (not a preference or suggestions) that OSes use the UEFI RT system reset call over SBI.

UEFI spec version vs a minimal subset

UEFI spec section 2.6 lists the various boot/runtime services and platform specific elements. If we mandate a specific version in BRS spec, it may mean that all of the things specified in the spec has to be implemented by the firmware.

For EDK2, it probably won't be an issue but it makes harder for any other firmware/boot loader to comply.

There are many platform specific requirements which may not be required.
Example:
If a platform includes USB bus support, then EFI_USB2_HC_PROTOCOL and EFI_USB_IO_PROTOCOL
must be implemented. An external device can support USB by producing a USB Host Controller Protocol.

If a platform includes an NVM Express controller, then EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL must
be implemented.

I think we should add a UEFI conformance profile for each recipe to make it easier. EBBR already defines a one for the its own UEFI subset.

@adurbin-rivos @andreiw

Dependency: ACPI - Define AML device for SPCR type 0x12 devices

Type 0x12 can describe NS16550-like UARTs that cannot be described by PNP0501 - the e.g. register stride, clock frequency. And there are other "tunables" which may be interesting to the OS driver. This should have it's own ACPIxxxx _CID.

Can model this on https://github.com/torvalds/linux/blob/master/Documentation/devicetree/bindings/serial/8250.yaml.

These seem like a good set. Should these use DSD DT?

• clock-frequency
• reg-offset
• reg-shift
• reg-io-width
• fifo-size

doc generate fail with: asciidoctor: FAILED: 'asciidoctor-mathematical' could not be loaded

:/c/n/riscv-os-a-see$ git submodule init
:/c/n/riscv-os-a-see$ git log -1
commit f2ea222 (HEAD -> main, origin/main, origin/HEAD)
Merge: 54a1a1c 3273c7b
Author: Andrei Warkentin [email protected]
Date: Tue May 23 22:50:38 2023 -0500

Merge pull request #40 from riscv-non-isa/spec-seeding

spec seeding

:~/c/n/riscv-os-a-see$ 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
Building asciidoc
asciidoctor-pdf
--attribute=mathematical-format=svg
--attribute=pdf-fontsdir=docs-resources/fonts
--attribute=pdf-style=docs-resources/themes/riscv-pdf.yml
--failure-level=ERROR
--require=asciidoctor-bibtex
--require=asciidoctor-diagram
--require=asciidoctor-mathematical
--out-file=riscv-brs-spec.pdf
header.adoc
asciidoctor: FAILED: 'asciidoctor-mathematical' could not be loaded
Use --trace for backtrace
make: *** [Makefile:9: build] Error 1
asciidoctor: FAILED: input file profiles.adoc is missing

Define trap (interrupt/exception) handler delegation

At this point, it is more a less coincidental which trap handlers an SBI may or may not delegate to an OS.
While OpenSBI handles e.g. unaligned access, this is not to be expected in general.

Now comes the hard part:
Should we define a set of what exactly is / should be delegated, or at least say that the OS should be prepared for anything to be delegated? It is crucial for the OS to know. Otherwise, there are dozens of possible combos of (non-)delegations.

ACPI_050/040 are too much (Was: Some optional requirements are written in an inflexible way)

Requirements are stated in a way that precludes vendor specific
behavior in certain cases.

For example, "the PCI Memory-mapped Configuration Space (MCFG) table
must only be present if and only if compatible non-hot-removable PCIe
segments are made available to the OS." Thus, implementors have the
option of (1) not implementing that feature, (2) implementing it
exactly as described, or (3) being out of compliance with the entire
specification. There is no latitude to comply with the BRS and
provide that feature in a vendor specific way.

Contrast to the way that ISA extensions are defined, considering for
example floating point (F&D). An implementation may (1) not implement
floating point, (2) implement floating point as described by the F&D
extensions, or (3) implement floating point in any other way. All
three options are compliant with the ISA specification. The only
prohibition is that option (3) cannot assert that it implements the
F&D extensions.

Dependency: RISC-V FFH

BRS Recipe Naming

The original https://docs.google.com/document/d/1X0TSbheEJjRGWhG2nzUnfIl_QcHWSuvd/edit# document called the recipes as "HI" and "VI", standing for "Horizontally-Integrated" and "Vertically-Integrated".

Mark didn't like the names, and we should think if better ones exist.

#3 uses BSR-H and BSR-V as a stop-gap. Personally, I'm a fan of using Vertical and Horizontal, perhaps clarifying that we're talking about standards. There is a precedent elsewhere - https://legalbeagle.com/13659495-according-to-osha-what-is-the-difference-between-vertical-horizontal-standards.html

To help thinking of alternate names, here is a rough break-down of H vs V:

"Horizontal":

• Enables wide set of OSVs, OEMs, IHV and SiPs to interop in a compatible manner.
• "team effort": one company builds Si, another packages into a board, another packages into box, yet another writes OS, yet another writes apps, yet another one sells and provides services
• servers, desktops, laptops

"Vertical":

• Purpose-built hardware + app + service
• One vendor controls everything from hardware and firmware to application/service and sales
• Examples: mobiles, embedded, cloud

Support for harts with asymmetric perf

Although the server HW TG is not spun up yet, the current WIP draft allows for "turbo boost max"-like implementations, where certain cores could support an even higher perf state. And this could mean P-core/E-core (bit.LITTLE-like) implementations too.

Need to figure out fw implications, including but not limited to:

• reporting capabilities per hart (static via RHCT or via AML?)
• Default boot state (do all cores boot at the same performance level? is the "boot" cpu the lowest performing one or the highest-performing one?)

The goal here is to cross the Ts and dot the I's so we don't end up in a world where someone builds a system that is compatible to the HW spec but somehow isn't fully expressible via the FW one.

Dependency: RIMT (IOMMU) ACPI table

Dependency: ACPI 6.6: CPPC

Definition of the term "platform", used in the document, is lacking

Testing & Conformance

We have a section about testing & conformance. We should fill it out and indicate the resources available as well as the proper verbiage as it's not 100%. Ken Dockser (@kdockser) indicated he'd help with the wording. Ken, do you have thoughts?

Secondary Hart Boot chapter

Sorry if this was discussed earlier in the TG that I did not attend. I couldn't find any context about this.
Is this supposed to be a booting guide style document that specifies the booting vs non booting hart state, assumptions ?

We are working on a booting guide doc for Linux. We can refer to that here if that is the intention.

Bibliography Not Building

I am not getting an error, but the bibliography is not showing up in the pdf. It could very well be my setup. @andreiw is it working for you?

Update SBI to v2.0