Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Assorted cleanup #70

Merged
merged 2 commits into from
Sep 7, 2023
Merged

Assorted cleanup #70

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
39dbd07
more acpi cleanup
Aug 25, 2023
9ea090b
get rid of chapter on secondary hart boot, as it's really hsm text an…
Aug 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 7 additions & 18 deletions acpi.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,31 +3,20 @@

The Advanced Configuration and Power Interface specification provides the OS-centric view of system configuration, various hardware resources, events and power management.

This section defines mandatory and optional ACPI requirements on top of the ones in the ACPI cite:[ACPI] and UEFI cite:[UEFI] specifications. Additional non-normative guidance may be found in the <<acpi-guidance, appendix>>.
This section defines the BRS-I mandatory and optional ACPI requirements on top of cite:[ACPI] and cite:[UEFI]. Additional non-normative guidance may be found in the <<acpi-guidance, appendix>>.

A compliant system must:

* [[acpi-64bit-clean]]Be 64-bits clean.
** RSDT must not be implemented, with RsdtAddress in RSDP set to 0.
** 32-bit address fields must be 0.
** <<acpi-guidance-64bit-clean, See additional guidance>>.
* <<acpi-hw-reduced, Implement a hardware-reduced ACPI model>>.
* Implement a firmware-first APEI model. (cite:[ACPI] Section 18.4)

[[acpi-hw-reduced]]
=== Hardware-Reduced ACPI Model

Compliant RISC-V systems only implement the HW-Reduced ACPI Model cite:[ACPI] (Section 4.1).
This means the hardware portion of cite:[ACPI] (Section 4) is not required or
supported. All functionality is instead provided through equivalent
software-defined interfaces and the complexity in supporting ACPI is reduced.

The following additional requirements apply:

* No FACS table.
* For the ACPI Platform Error Interfaces (APEI) support:
** There is 1 event for non-fatal error signaling (cite:[ACPI] Section 18.3.2.7.2)
** There is 1 NMI-equivalent signal for use in fatal errors (cite:[ACPI] Section 18)
* [[acpi-hw-reduced]]Implement the HW-Reduced ACPI Mode.
** No FACS table.
** <<acpi-guidance-hw-reduced, See additional guidance>>.
* Implement a firmware-first ACPI Platform Error Interface (APEI) model (cite:[ACPI] Section 18.4).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this imply this is the only model? Or that something is exposed as opt-in for firmware first.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you referring to the APEI portion? I just moved the text, but we can take the APEI requirements out for now if we need to dig into the details here (e.g. my personal opinion is that for BRS-I we mandate APEI, but there may be more work on the APEI side - but that's not really a BRS task by itself)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ya, I was. I know you were moving things, but I did want to ask this question about the implications. I was mainly talking about 'firrmware-first APEI' as the only option. If that's the case, that's a discussion to be had. I can put it on the agenda for the next meeting.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, let's put that on the agenda. I raised #71 so we don't lose track of it. I'll merge this pull request meanwhile.

** 1 event for non-fatal error signaling (cite:[ACPI] Section 18.3.2.7.2)
** 1 NMI-equivalent signal for use in fatal errors (cite:[ACPI] Section 18)

=== Additional ACPI Table Requirements

Expand Down
4 changes: 0 additions & 4 deletions appendices.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,6 @@ implementation choices, suggestions, historical context, etc.
==== Recipes Guidance
include::non-normative/recipes.adoc[]

[[secondary-guidance]]
==== Secondary Hart Boot Guidance
include::non-normative/secondary.adoc[]

[[uefi-guidance]]
==== UEFI Implementation Guidance
include::non-normative/uefi.adoc[]
Expand Down
4 changes: 4 additions & 0 deletions brs.bib
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,10 @@ @electronic{TcgEfiPlat
title = {TCG EFI Platform Specification},
url = {https://trustedcomputinggroup.org/resource/tcg-efi-platform-specification/},
}
@electronic{TcgAcpi,
title = {TCG ACPI Specification},
url = {https://trustedcomputinggroup.org/resource/tcg-acpi-specification/},
}
@electronic{MSUefiCaRequirements,
title = {UEFI memory mitigations},
url = {https://learn.microsoft.com/en-us/windows-hardware/drivers/bringup/uefi-ca-memory-mitigation-requirements},
Expand Down
1 change: 0 additions & 1 deletion header.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,6 @@ include::intro.adoc[]
include::recipes.adoc[]
include::hart.adoc[]
include::sbi.adoc[]
include::secondary.adoc[]
include::uefi.adoc[]
include::acpi.adoc[]
include::smbios.adoc[]
Expand Down
30 changes: 24 additions & 6 deletions non-normative/acpi.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,35 @@ tables known as Root System Description Table (RSDP) passed to the OS
via a EFI_ACPI_20_TABLE_GUID configuration table in the UEFI firmware.
The Operating System uses this address to locate all other ACPI tables.

[[acpi-guidance-64bit-clean]] ACPI started as a specification for 32-bit systems,
Certain implementations may make use of the RISC-V Functional Fixed hardware Specification cite:[FFH].

[[acpi-guidance-64bit-clean]]
===== 64-bits Clean

ACPI started as a specification for 32-bit systems,
so certain tables with physical address pointers (e.g. RSDP, FADT) allow for reporting
either 32-bit or 64-bit values using different fields. For the sake of simplicity
and consistency, the BRS disallows the use 32-bit address fields in such structures
and disallows the use of 32-bit only structures (thus, RSDP must not be implemented,
as the XSDT is a direct replacement). Thus, the ACPI tables are allowed to be
located in any part of the physical address space.

Certain implementations may make use of the RISC-V Functional Fixed hardware Specification cite:[FFH].
[[acpi-guidance-hw-reduced]]
===== Hardware-Reduced ACPI

Compliant RISC-V systems only implement the HW-Reduced ACPI Model cite:[ACPI] (Section 4.1).
This means the hardware portion of cite:[ACPI] (Section 4) is not required or
supported. All functionality is instead provided through equivalent
software-defined interfaces and the complexity in supporting ACPI is reduced.

<<acpi-guidance-tab-min>> summarizes the minimum set of structures that must exist to support basic booting of RISC-V system with ACPI support. <<acpi-guidance-tab-opt>> lists additional possible ACPI tables based on the optional features that can be supported. The latter is not meant to be exhaustive and mostly focuses on tables that
have specific guidance or that expected to be frequently implemented.
===== Table Guidance
<<acpi-guidance-tab-min>> summarizes the minimum set of structures
that must exist to support basic booting of RISC-V system with ACPI
support. <<acpi-guidance-tab-opt>> lists additional possible ACPI
tables based on the optional features that can be supported. The
latter is not meant to be exhaustive and mostly focuses on tables that
have specific guidance or that are expected to be frequently
implemented.

.*Minimum required ACPI System Description Tables*
[[acpi-guidance-tab-min]]
Expand All @@ -23,7 +40,7 @@ have specific guidance or that expected to be frequently implemented.
|ACPI Table |ACPI Section|Note
|Root System Description Pointer (RSDP) |5.2.5 | See <<acpi-64bit-clean, high-level requirements>>.
|Extended System Description Table (XSDT) |5.2.8 | Contains pointers to other tables.
|Fixed ACPI Description Table (FADT) |5.2.9 | See <<acpi-hw-reduced>> and <<acpi-guidance-fadt, the notes below>>.
|Fixed ACPI Description Table (FADT) |5.2.9 | See <<acpi-hw-reduced>>, <<acpi-guidance-hw-reduced>> and <<acpi-guidance-fadt, the notes below>>.
|Differentiated System Description Table (DSDT)|5.2.11.1 | See <<acpi-aml>> and <<acpi-guidance-aml, the notes below>>.
|Multiple APIC Description Table (MADT) |5.2.12 | See <<acpi-guidance-madt, the notes below>>
|RISC-V Hart Capabilities Table (RHCT) |New | Communicates
Expand All @@ -39,8 +56,9 @@ information about certain capabilities like ISA string, cache and MMU info.
|===
|ACPI Table |ACPI Section |Note
|Memory-mapped Configuration space (MCFG) |cite:[PCIFW] |See <<acpi-mcfg>> and <<acpi-guidance-pcie, the notes below>>
| Secondary System Description Table (SSDT) |5.2.11.2 |See <<acpi-aml>> and <<acpi-guidance-aml, the notes below>>.
|Secondary System Description Table (SSDT) |5.2.11.2 |See <<acpi-aml>> and <<acpi-guidance-aml, the notes below>>.
|Serial Port Console Redirection (SPCR) |cite:[SPCR] |See <<acpi-spcr>> and <<acpi-guidance-spcr, the notes below>>
|ACPI Table for TPM 2.0 (TPM2) |cite:[TcgAcpi]|If the platform supports TPM 2.0
|System Resource Affinity Table (SRAT) |5.2.16 |If the platform supports NUMA
|System Locality Information Table (SLIT) |5.2.17 |If the platform supports NUMA
|Boot Error Record Table (BERT) |18.3.1 |If ACPI RAS is supported
Expand Down
1 change: 0 additions & 1 deletion non-normative/secondary.adoc
View file
Open in desktop

This file was deleted.

6 changes: 6 additions & 0 deletions non-normative/uefi.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,3 +48,9 @@ frame buffer of the graphics adapters directly accessible (i.e.
EFI_GRAPHICS_PIXEL_FORMAT is not PixelBltOnly). The
FrameBufferBase must be reported as a hart MMIO address, not as a
bus address (e.g. for a PCIe video device).

[[uefi-guidance-harts]]
====== Hart Management

If the harts are being started or stopped internally by a firmware implementation, this should happen before completing the EFI_EVENT_GROUP_READY_TO_BOOT event, and all secondary harts should remain offline from that point on. This ensures an OS loader is entered with an OS-compatible state for the harts.

2 changes: 2 additions & 0 deletions sbi.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ The SBI v1.0 specification allows optional SBI extensions. However, the
following optional extensions are mandatory for a compliant system.

* SBI Hart State Management (HSM)
** HSM is used by an OS for starting up, stopping, suspending and querying the status of secondary harts.
** <<uefi-guidance-harts, See additional guidance>>.

* SBI System Reset (SRST)
** See <<uefi-resetsystem>> for additional notes on SRST use by a UEFI implementation and by an OS.
Expand Down
6 changes: 0 additions & 6 deletions secondary.adoc
View file
Open in desktop

This file was deleted.