Add initial test specification (#178)

Signed-off-by: Haibo Xu <[email protected]>

Makefile

@@ -21,6 +21,9 @@ riscvintl/riscv-docs-base-container-image:latest
 HEADER_SOURCE := header.adoc
 PDF_RESULT := riscv-brs-spec.pdf
 
+TS_HEADER_SOURCE := brs_ts_header.adoc
+TS_PDF_RESULT := riscv-brs-ts.pdf
+
 ASCIIDOCTOR_PDF := asciidoctor-pdf
 OPTIONS := --trace \
            -a compress \
@@ -52,11 +55,13 @@ build:
 build-container:
 	@echo "Starting build inside Docker container..."
 	$(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)"
+	$(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(TS_PDF_RESULT) $(TS_HEADER_SOURCE)"
 	@echo "Build completed successfully inside Docker container."
 
 build-no-container:
 	@echo "Starting build..."
 	$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)
+	$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(TS_PDF_RESULT) $(TS_HEADER_SOURCE)
 	@echo "Build completed successfully."
 
 clean:

brs_tests.adoc

@@ -0,0 +1,189 @@
+== BRS Test Specification
+
+=== Hart Requirements
+
+[width=100%]
+[%header, cols="8,25"]
+|===
+| ID#            ^| Algorithm
+| `ME_HR_010_010` a| For each application processor hart:
+
+                    . Determine the ISA string for that hart from
+                    .. RHCT table if ACPI was used
+                    .. riscv,isa-base and riscv,isa-extensions nodes if DT was used
+                    . Parse the ISA string and verify that all mandatory extensions
+                      in `RVA20S64` profile cite:[Profile] are supported.
+                    . Verify that the ISA string matches that of hart 0.
+                    . Report the ISA string of hart 0 into the test output log.
+|===
+
+<<<
+
+=== SBI Requirements
+
+[width=100%]
+[%header, cols="8,25"]
+|===
+| ID#            ^| Algorithm
+| `ME_SBI_010_010` | . Get the SBI version by sbi_get_sbi_spec_version().
+                     . Verify that the version is v2.0 or later.
+                     . Report the version into the test output log.
+| `ME_SBI_020_010` | . See `ME_SBI_010_010`.
+                     . Probe the presence of HSM extension by sbi_probe_extension().
+                     . Verify that the result is true.
+| `OE_SBI_030_010` | . If Sstc extension was present(See `ME_HR_010_010`)
+                     .. Report Sstc was present and Skip the test.
+                     . Else
+                     .. Probe the presence of TIME extension by sbi_probe_extension().
+                     .. Verify that the result is true.
+| `OE_SBI_040_010` | . If Ssaia extension was present(See `ME_HR_010_010`)
+                     .. Report Ssaia was present and Skip the test.
+                     . Else
+                     .. Probe the presence of sPI extension by sbi_probe_extension().
+                     .. Verify that the result is true.
+| `OE_SBI_050_010` | . If Ssaia extension was present(See `ME_HR_010_010`)
+                     .. Report Ssaia was present and Skip the test.
+                     . Else
+                     .. Probe the presence of RFNC extension by sbi_probe_extension().
+                     .. Verify that the result is true.
+| `OE_SBI_060_010` | . If Smcsrind,Sscsrind,Smcdeleg,Ssccfg extensions
+                       were present(See `ME_HR_010_010`).
+                     .. Report Smcsrind,Sscsrind,Smcdeleg,Ssccfg  was present and
+                        Skip the test.
+                     . Else
+                     .. Probe the presence of PMU extension by sbi_probe_extension().
+                     .. Verify that the result is true.
+|===
+
+<<<
+
+=== BRS-I UEFI Requirements
+
+[width=100%]
+[%header, cols="8,25"]
+|===
+| ID#            ^| Algorithm
+| `ME_UEFI_010_010` | _FIXME_.
+| `ME_UEFI_020_010` | _FIXME_.
+| `ME_UEFI_030_010` | _FIXME .
+| `OE_UEFI_040_010` | _FIXME .
+| `OE_UEFI_050_010` | _FIXME .
+| `ME_UEFI_060_010` | _FIXME .
+| `ME_UEFI_070_010` | _FIXME .
+|===
+
+<<<
+
+==== BRS-I UEFI Security Requirements
+
+[width=100%]
+[%header, cols="8,25"]
+|===
+| ID#            ^| Algorithm
+| `OE_USEC_010_010` | _FIXME_.
+| `OE_USEC_020_010` | _FIXME_.
+|===
+
+<<<
+
+==== BRS-I UEFI IO Requirements
+
+[width=100%]
+[%header, cols="8,25"]
+|===
+| ID#            ^| Algorithm
+| `OE_UIO_010_010` | _FIXME_.
+| `OE_UIO_020_010` | _FIXME_.
+|===
+
+<<<
+
+==== BRS-I UEFI Runtime Service Requirements
+
+[width=100%]
+[%header, cols="8,25"]
+|===
+| ID#            ^| Algorithm
+| `OE_URT_010_010` | _FIXME_.
+| `OE_URT_020_010` | _FIXME_.
+| `ME_URT_030_010` | _FIXME_.
+| `ME_URT_040_010` | _FIXME_.
+| `ME_URT_050_010` | _FIXME_.
+| `OE_URT_060_010` | _FIXME_.
+|===
+
+<<<
+
+==== BRS-I UEFI Firmware Update Requirements
+
+[width=100%]
+[%header, cols="8,25"]
+|===
+| ID#            ^| Algorithm
+| `OE_UFU_010_010` | _FIXME_.
+| `OE_UFU_020_010` | _FIXME_.
+| `OE_UFU_030_010` | _FIXME_.
+| `OE_UFU_040_010` | _FIXME_.
+|===
+
+<<<
+
+=== BRS-I ACPI Requirements
+
+[width=100%]
+[%header, cols="8,25"]
+|===
+| ID#            ^| Algorithm
+| `ME_ACPI_010_010` | _FIXME_.
+| `ME_ACPI_020_010` | _FIXME_.
+| `ME_ACPI_030_010` | _FIXME_.
+| `OE_ACPI_040_010` | _FIXME_.
+| `OE_ACPI_050_010` | _FIXME_.
+| `OE_ACPI_060_010` | _FIXME_.
+| `OE_ACPI_080_010` | _FIXME_.
+|===
+
+<<<
+
+==== BRS-I ACPI Methods and Objects Requirements
+
+[width=100%]
+[%header, cols="8,25"]
+|===
+| ID#            ^| Algorithm
+| `ME_AML_010_010` | _FIXME_.
+| `OE_AML_020_010` | _FIXME_.
+| `OE_AML_030_010` | _FIXME_.
+| `ME_AML_040_010` | _FIXME_.
+| `OE_AML_050_010` | _FIXME_.
+| `ME_AML_060_010` | _FIXME_.
+| `OE_AML_070_010` | _FIXME_.
+| `OE_AML_080_010` | _FIXME_.
+| `ME_AML_090_010` | _FIXME_.
+| `ME_AML_100_010` | _FIXME_.
+|===
+
+<<<
+
+=== SMBIOS Requirements
+
+[width=100%]
+[%header, cols="8,25"]
+|===
+| ID#            ^| Algorithm
+| `OE_SMBIOS_010_010`  | _FIXME_
+| `ME_SMBIOS_020_010`  | _FIXME_
+| `OE_SMBIOS_030_010`  | _FIXME_
+| `OE_SMBIOS_040_010`  | _FIXME_
+| `OE_SMBIOS_050_010`  | _FIXME_
+| `OE_SMBIOS_060_010`  | _FIXME_
+| `OE_SMBIOS_070_010`  | _FIXME_
+| `OE_SMBIOS_080_010`  | _FIXME_
+| `OE_SMBIOS_090_010`  | _FIXME_
+| `OE_SMBIOS_100_010`  | _FIXME_
+| `OE_SMBIOS_110_010`  | _FIXME_
+| `ME_SMBIOS_120_010`  | _FIXME_
+| `OE_SMBIOS_130_010`  | _FIXME_
+|===
+
+<<<

brs_ts_header.adoc

@@ -0,0 +1,59 @@
+[[header]]
+:description: RISC-V Boot and Runtime Services Test Specification
+:company: RISC-V.org
+:url-riscv: http://riscv.org
+:doctype: book
+:preface-title: Preamble
+:colophon:
+:appendix-caption: Appendix
+:imagesdir: images
+:title-logo-image: image:risc-v_logo.svg[pdfwidth=3.25in,align=center]
+// Settings:
+:experimental:
+:reproducible:
+:imagesoutdir: images
+:bibtex-file: brs.bib
+:bibtex-order: appearance
+:bibtex-style: ieee
+:icons: font
+:lang: en
+:listing-caption: Listing
+:sectnums:
+:toc: left
+:toclevels: 4
+:source-highlighter: pygments
+ifdef::backend-pdf[]
+:source-highlighter: coderay
+endif::[]
+:data-uri:
+:hide-uri-scheme:
+:stem: latexmath
+:footnote:
+:xrefstyle: short
+
+= RISC-V Boot and Runtime Services Test Specification
+BRS Task Group
+
+// Preamble
+[WARNING]
+.This document is in the link:http://riscv.org/spec-state[Development state]
+====
+Assume everything can change. This draft specification will change before
+being accepted as standard, so implementations made to this draft
+specification will likely not conform to the future standard.
+====
+
+[preface]
+== Copyright and license information
+This specification is 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/.
+
+Copyright 2024 by RISC-V International.
+
+[preface]
+include::contributors.adoc[]
+include::brs_ts_intro.adoc[]
+include::brs_tests.adoc[]
+include::bibliography.adoc[]

brs_ts_intro.adoc

@@ -0,0 +1,70 @@
+[[intro]]
+
+== Introduction
+
+The RISC-V Boot and Runtime Services Test specification defines a set of tests to
+verify if the requirements specified in RISC-V BRS specification are implemented.
+The tests specified in this specification are not intended to exhaustively verify
+the implementation. In most cases the tests only check for existence of the feature.
+Future versions of this specification may include more exhaustive tests.
+
+The tests in this specification are documented use the following format:
+
+[width=100%]
+[%header, cols="8,20"]
+|===
+| TEST_ID#       ^| Test algorithm
+| AB_CAT_NNN_MMM a| The `CAT_NNN` identifies a requirement in the RISC-V BRS
+                    specification. Each requirement is associated with one or
+                    more tests identified by `MMM`. The test IDs are prefixed
+                    with two character prefix - `AB`.                          +
+                                                                               +
+                    If character in position `A` is `M` then the test is for a
+                    requirement that MUST be supported and this test MUST pass.
+                    If character in position `A` is `O` then the test is for a
+                    requirement that SHOULD or MAY be supported; such tests may
+                    be skipped if the requirement is not implemented. The tests
+                    record if optional features were present in the test output
+                    log.                                                       +
+                                                                               +
+                    The character in position `B` indicates the nature of the
+                    test. If this character is `F` then the test exercises some
+                    or all of the functionality associated with the feature. If
+                    the character is `E` then the test determines for evidence
+                    that the feature is implemented (e.g., check ACPI tables)
+                    but does not functionally exercise the feature.
+
+|===
+
+This specification groups the tests in the following broad categories:
+
+* Hart
+* SBI
+* UEFI
+* ACPI
+* SMBIOS
+
+=== Glossary
+
+Most terminology has the standard RISC-V meaning. This table captures other
+terms used in the document.
+
+.Terms and definitions
+[width=90%]
+[%header, cols="5,20"]
+|===
+| Term            ^| Definition
+| ACPI             | Advanced Configuration and Power Interface cite:[ACPI].
+| BRS              | RISC-V Boot and Runtime Services Specification.
+| BRS-I            | Boot and Runtime Services recipe targeting interoperation across different software suppliers.
+| BRS-B            | Boot and Runtime Services recipe using a bespoke solution.
+| DT               | DeviceTree cite:[DT].
+| EBBR             | Embedded Base Boot Requirements Specification cite:[EBBR].
+| OSV              | Operating System Vendor.
+| OS               | Operating System or Hypervisor.
+| Profile          | RISC-V Profile cite:[Profile].
+| SBI              | RISC-V Supervisor Binary Interface Specification cite:[SBI].
+| SMBIOS           | System Management BIOS (SMBIOS) Reference Specification cite:[SMBIOS].
+| SoC              | System on a chip, a combination of processor and supporting chipset logic in single package.
+| UEFI             | Unified Extensible Firmware Interface Specification cite:[UEFI].
+|===