diff --git a/Makefile b/Makefile index 6638201..5b085cc 100644 --- a/Makefile +++ b/Makefile @@ -55,10 +55,7 @@ OPTIONS := --trace \ $(XTRA_ADOC_OPTS) \ -D build \ --failure-level=ERROR -REQUIRES := --require=asciidoctor-bibtex \ - --require=asciidoctor-diagram \ - --require=asciidoctor-lists \ - --require=asciidoctor-mathematical +REQUIRES := --require=asciidoctor-bibtex .PHONY: all build clean build-container build-no-container build-docs diff --git a/src/acceptance_criteria.adoc b/src/acceptance_criteria.adoc new file mode 100644 index 0000000..7bedbd6 --- /dev/null +++ b/src/acceptance_criteria.adoc @@ -0,0 +1,141 @@ +[[acceptance_criteria]] +== Acceptance Criteria + +*Version:* 1.2 + +*One line description:* What must be complete before TSC can approve a specification for ratification + +*Author(s)*: Mark I Himelstein, Stephano Cetola + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) +|1.2 |2024-01-12 |Clarify escalation path through CTO |Jeff Scheel + +|1.1 |2022-10-03 |Update criteria regarding infrastructure. See section +"Waivers". |Stephano Cetola + +|1.0 |2022-06-05 |TSC Approved, vote completed |Stephano Cetola + +|0.1 |2022-04-22 |This is based off the old +https://docs.google.com/document/d/1Hp9ZZSzjk6Tp2pIvh33mNCj6wAoJCEqsdENQUTSruQg/edit?usp=sharing[Definition +of Done] policy as well as the new +https://docs.google.com/spreadsheets/d/1iXUZdNH6aZ-EDxsOqhYW82Ha6L7K4uVZt0-Rw9ZR-nY/edit?usp=sharing[ISA +Status Checklist] |Stephano Cetola +|=== + +=== Rationale + +This document acts as a minimum viable definition of tasks, while the +https://docs.google.com/spreadsheets/d/1iXUZdNH6aZ-EDxsOqhYW82Ha6L7K4uVZt0-Rw9ZR-nY/edit?usp=sharing[ISA +Status Checklist] contains the details. For any given specification, see +the relevant status checklist for how that specification meets the +requirements defined in this policy. + +=== Related documentation + +==== Milestone +See the +https://docs.google.com/presentation/d/1nQ5uFb39KA6gvUi5SReWfIQSiRN7hp6z7ZPfctE4mKk/edit?usp=sharing[Specification +Lifecycle and Milestone Definitions] for more detailed milestone +definitions. + +==== Task + +See the +https://docs.google.com/spreadsheets/d/1iXUZdNH6aZ-EDxsOqhYW82Ha6L7K4uVZt0-Rw9ZR-nY/edit?usp=sharing[ISA +Status Checklist Template] and milestone tabs for details on the tasks +required for each milestone. +https://docs.google.com/spreadsheets/d/1D2YFdbX0ikurULz71VRP2T8LCTSnWtBS-CUwJYR_VA8/edit?usp=sharing[Tasks +for Non-ISA Specifications] are much more flexible based on the nature +of Non-ISA Specifications. This document is meant only as a guide for +Non-ISA Specifications and Architectural Overview specifications. + +=== Policy + +The TG must complete or provide waivers for all of the +link:#list-of-tasks[List of Tasks] to reach the given milestone. The TG +must maintain and keep up to date their +https://docs.google.com/spreadsheets/d/1iXUZdNH6aZ-EDxsOqhYW82Ha6L7K4uVZt0-Rw9ZR-nY/edit?usp=sharing[status +checklist] by: + +. Identifying the work that needs to be done + +. Identifying and documenting the resources needed + +. Providing milestone date projections and a monthly status updates + +. Identifying any delays and providing mitigation plans + +==== List of Tasks + +===== Freeze + +. *Document Complete* - the document must describe the semantics of +instructions or operations and any other extension-specific visible +state. + +. *Opcode Support* - there must be enough opcode support for GCC to be +functional but not optimized. + +. *Simulators* - There must be enough simulator support so that basic +RISC-V tests can be run. See the +https://docs.google.com/document/d/1bXzONWVxXCp0wUigVDE2bQDU13uQRsZM80pmbXbERQc/edit?usp=sharing[Architectural +Compatibility Test policy] for more details. + +. *Application Binary Interface* - All applicable ABIs must be updated +as relevant and changes must be discussed during architecture review + +. *Compiler Support* - Support GCC without optimizations. + +. *Architecture Compatibility Tests* (ACT) - Create tests and test +input. See the +https://docs.google.com/document/d/1bXzONWVxXCp0wUigVDE2bQDU13uQRsZM80pmbXbERQc/edit?usp=sharing[Architectural +Compatibility Test policy] for details. + +. *Sail Golden Model* - Work with RISC-V staff to update the Sail Golden +Model as appropriate. + +. *Architecture Review* - See the +https://docs.google.com/document/d/1Ng03zfzUBoUacATyV1mxQE9oLVeyBOdzGseLD15mdFo/edit?usp=sharing[Architecture +Review Policy] for details (currently in development). + +. *Proof of Concept* (POC) - Propose POCs to the governing committees +for approval, or approve the waiver of PoC at the governing committee’s +discretion. The TSC must be informed of this waiver and may reject the +waiver. The committee may ask for revisions in the POC. + +. *RISC-V Publication Policies* - Abide by other pertinent policy +(e.g. encumbered information, friendly terminology, anonymous +contributor) currently in development. + +===== Ratification Ready + +. *Resolve Freeze Waivers* - Either resolve freeze waivers or get new +waivers for vote-ready updating the status of the old waivers. + +. *Document Complete* - Complete updates to the specification based on +review comments. + +. *Architecture Review* - See the +https://docs.google.com/document/d/1Ng03zfzUBoUacATyV1mxQE9oLVeyBOdzGseLD15mdFo/edit?usp=sharing[Architecture +Review Policy] currently in development. This step is only required if +there were changes after public review. + +. *Unified Discovery* - TBD, waiting on Unified Discovery specification +to be ratified. + +. *Regression Testing* - Identify and test interactions with previously +ratified specifications. + +. *Architecture Compatibility Tests* (ACT) - All tests and inputs should +be updated with any changes since public review. + +. *Industry Standard Tests* - Generate correct test results from any +appropriate industry-available license-friendly tests (e.g. IBM floating +point tests, AES tests, etc). + +. *OS Enablement* - See the +https://docs.google.com/document/d/17_iBms-zh55SB1Hkjn0cp7Ns5LOdcnlvsN88ymWoRzI/edit?usp=sharing[policy] +for details, currently in development. + +. *RISC-V Profiles* - The extension(s) must be included in at least 1 +RISC-V profile. + +. *RISC-V Publication Policies* - Abide by other pertinent policy +(e.g. encumbered information, friendly terminology, anonymous +contributor) currently in development. + +==== Waivers + +Waivers for Freeze are approved by Tech Chairs 6+ majority vote. Waivers +for ratification are approved by TSC 6+ majority vote. + +For ratification, any infrastructure that does not exist and will not +exist within the next year requires a Committee Chairs majority vote to +waive, and for the TSC to be notified of the waiver (and may override). + +=== Exceptions + +The CTO is the escalation path for all policy issues, with the authority +to resolve them or, if necessary, escalate further to the TSC or the +BOD. diff --git a/src/act.adoc b/src/act.adoc new file mode 100644 index 0000000..5045666 --- /dev/null +++ b/src/act.adoc @@ -0,0 +1,334 @@ +[[act]] +== Architectural Compatibility Test + +*Version:* 1.2 + +*One line description:* These are the rules that explain the rationale +for, and the requirements for running and reporting results of RISC-V +architectural tests, and conditions for waiving failures. + +*Author(s):* Allen Baum, Ken Dockser + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.2 |2024-01-16 |Change escalation path to occur through CTO +|Jeff Scheel + +|1.1 |2021-09-30 |added discussion about non-standard extensions. +|Allen Baum + +|1.0 |2021-03-20 |Initial version |Allen Baum, Ken Dockser +|=== + + +=== Rationale + +RISC-V Architectural Tests (ACT) are an evolving set of tests that are +created to help ensure that SW written for a given RISC-V Profile will +run on all implementations that comply with that profile. + +These tests also help ensure that the implementer has both understood +and implemented the specification. + +The RISC-V Architectural Tests test suite is a minimal filter. Passing +the tests and having the results approved by RISC-V International is one +of the prerequisites to being listed as RISC-V ISA Compatible. Details +of RISC-V trademark usage may be found on the RISC-V International Web +page at https://riscv.org/. + +Passing the RISC-V Architectural Tests does *_not_* mean that the design +complies with the RISC-V Architecture. These are only a basic set of +tests. + +The RISC-V Architectural Tests are *_not_* a substitute for rigorous +design verification; it is the responsibility of the implementer to +deploy extensive testing. + +=== Policy + +==== Who Must Test + +Anyone who develops RTL or a functional model for a RISC-V core and +wants to be listed as RISC-V ISA Compatible (e.g., in order to use the +RISC-V Compatible trademarks) needs to run the tests and file the +resulting test report as a step in the RISC-V Compatible listing +process. + +An entity (e.g., a value-added reseller) who has licensed core IP from a +developer and does not alter that IP can rely on the developer’s RISC-V +ISA Compatible listing. This includes cases where the entity has +selected configuration parameters from a range of values provided by the +developer, as long as the core with those chosen parameters is listed as +RISC-V Compatible. An entity that has otherwise modified the IP must get +the new design listed as RISC-V ISA Compatible by passing the +appropriate RISC-V ACT and by self-certifying that the changed design is +RISC-V compatible. + +==== What Must be Tested + +The RTL or functional model of the core design must run and pass all of +the tests within the ACT that RISC-V International says are required for +the targeted profile. + +In any of these cases, implementers must provide a simulation +environment (RTL or functional) with sufficient resources to run the +required ACT tests in the framework that selects tests, configures the +reference model to generate appropriate reference signatures, and +generates a test report based on comparing the reference model’s +signature with the implementation’s signature file. These simulation +environment resources include, but are not necessarily limited to: +sufficient memory capacity to load and run the tests, the reference +model, the architectural test repository, the tools needed to compile, +link, load and run the tests, the ability to respond to the signal that +the test is complete, and the ability to extract the resulting test +signature from the memory and save it in a file. + +Unless specified otherwise by RVI, the reference model to be used is the +Sail RISC-V Sequential Emulator produced from the most recently released +Sail Formal Specification of the RISC-V ISA. When the Sail Formal +Specification doesn’t yet fully support all of the necessary features of +the ISA, RVI may specify that the SPIKE emulator is to be used. In some +rare cases, RVI may specify that the QEMU emulator is to be used. In all +cases, RVI will specify which versions of the emulators to use. + +Each release version of ACT will document the version of the toolchain +utilities required to support the instructions used for that version of +the tests in a repository README file. This will also include which +reference model to use for the test as well as any other environmental +requirements (e.g., amount of RAM). + +==== Where to Report Test Results + +The ACT framework will generate a test report file with the name + +-.html with the in YYYY-MM-DD format +using GMT as the time zone. The is a string that identifies +which version of an implementer’s core is being tested.. + +In addition to pass/fail indications for each individual test that is +run, the report will include: + +* For any failures, the test case that failed, the expected value, and +the actual value found, + +* The ISA string that describes the ISA, extensions, and sub-extensions +implemented, + +* Any optional feature and configuration parameters allowed by the +architecture that are used, defined by listing a YAML formatted file +using the schema defined by the riscv-config format (see +https://riscv-config.readthedocs.io/en/latest/overview.html), + +* The vendor and implementation IDs that the DUT will report in those +respective CSRs (should be in the YAML feature/config file), + +NOTE: these may be zero if unimplemented + +* Name, commit hash, and either version tags or git commit date (in ISO +8601 UTC format w/ offset 00:00) of tools used : + +** Toolchain + +** reference model + +** Architecture Compatibility Test (ACT) suite, + +** riscv-config (for v3 of the framework) + +Vendors can submit their test results by filing a Pull Request that adds +the test report into a directory named for the vendor in the +https://github.com/riscv/riscv-arch-test-reports repository + +==== When to Report Test Results + +To retain their RISC-V ISA Compatibility listing, cores must pass the +ACT yearly if ACT tests, toolchain, reference simulators, or framework +change from those used to generate the test report, and issue errata if +new issues are found. + +==== Test-Case Waivers + +There are some special cases where it is not possible for an +implementation to pass all of the tests due to issues that may be +outside of the implementer’s control. A Test-Case Waiver is special +permission granted to exclude a test-case (or in some situations, test +cases) from the required tests. This allows implementations to +conditionally pass the ACT as long as all non-waived test cases pass. + +A waiver request must be filed as an issue in the test-report github +repository specifically requesting the waiver and mentioning the Pull +Request number of the filed test report. In all cases, the appropriate +ISA Committee and the SW Committee (or other appropriate non-ISA +committee) must approve using a majority vote to approve each waiver for +the specific design and test. The approval will be documented by filing +it into the same test-report github repository with a name containing +the same PR number as the waiver. + +Waivers are categorized into Flawed-Test,Constraint-Based, and +Errata-Based types. + +===== Flawed-test test-case waiver + +If there is a demonstrable bug in the test, reference model, or tool +chain that causes a test to fail, a Flawed-Test Test-Case Waiver may be +requested. Flawed-Tests include cases where the reference model produces +a result that differs from what the implementation produces, and that +result is one of several results that is considered correct by the rules +of the ISA (e.g. WARL behavior that tests don’t support). + +To be clear, a waiver is not to be requested -– and will not be granted +-– due to + +* a bug in the design. + +* Cases that result from toolchain version that has not been tested to +work with the version listed as being used in the reference model +test-report for the most recent test-suite. + +* cases where there is an ambiguity or misinterpretation of the +architecture. Cases that involve architectural ambiguity should be +resolved by clarification in the specification. + +===== Constraint-based test-case waiver + +Constraint waivers may be granted in special cases including when: + +. An implementation has architecturally valid configurations that +interfere with the ability of tests to run at reset + +. An Implementation establishes locked architecturally valid +configurations after reset that interfere with the ability of tests to +run. + +In order to qualify for and be granted a constraint-based waiver: + +* The implementer must document the constraint and its rationale to TSC, +and demonstrate that it is an architecturally valid configuration. + +===== Errata-based test-case waiver + +Errata-based waivers may be granted in special cases including when: + +. An implementation fails an existing architectural test + +. An implementation has previously passed architectural tests, but fails +a subsequently released test after production or within 6 months before +product manufacturing release, such that fixing the design would cause +an undue hardship to the implementer (e.g., the design is in final +manufacturing stages). + +. An implementation has a known architectural flaw that is not covered +by an architectural test (in which case a test for that case should be +added to the test suite if possible). + +. A RISC-V Compatible listed design either + +** fails subsequently released ACT tests, or + +** is reported to have an architectural incompatibility , or +a design was given a test-case waiver, fails the new test due +to a bug, but the new test-case was not made available in a reasonable +amount of time such that fixing the design would cause an undue hardship +to the implementer (e.g., the design is in final manufacturing stages). + +In order to qualify for and be granted an errata-based waiver, + +* The implementer must provide the appropriate ISA committee (i.e., +privileged or unprivileged) and SW or other HC with a detailed _erratum_ +(as to be defined in the forthcoming Errata Policy Document) covering +the bugs resulting in any and all failures of test cases. + +* the implementer must properly classify each individual erratum in the +errata as "low impact" (to be defined in the Errata Policy, until then +defined as: easily worked around with minimal impact to general +performance and to SW complexity), and provide a remediation process, or +justification of why remediation is unnecessary. + +If approved, the implementer is required to publish the errata on the +RISC-V website (and/or other appropriate location as determined by the +TSC) and make it otherwise readily available to users and coders. The +RVI Board and Marketing organization and TSC will be informed of the +decision by the ISA committee and the approval or disapproval filed in +the same github folder as the waiver request. If the implementer wants +to continue the non-conformant behavior, then they must change the +designation of that instanceID from compatible to custom. If they will +be conformant in the next revision of their product, they can mark +themselves as compatible with errata. + + +NOTE: _(this must be mentioned in branding or ACT policy)_ + +NOTE: Errata-based waivers do not transfer to subsequent physical +implementations (e.g., the physical design is substantially changed) as +these are considered new designs; implementers are expected to use this +opportunity to fix known bugs. + +==== Test-case waiver conditions + +When a test-case waiver is granted, it + +* only applies to a specific test case, not to an entire test + +* only applies to the version of the design to which it was granted + +* only lasts until the test case has been corrected or replaced +(flawed-test waiver) at which point the design must pass the corrected +test or request an errata-based waiver. + +In no circumstances shall a test-case waiver be viewed as a waiver of an +architectural requirement that is not subsequently relaxed in the spec. +Furthermore, no software or hardware may rely on the behavior of the +design in the waived test case other than to determine if the design +contains the issue. + +If any test-cases are granted waivers, and all other required test cases +and tests have passed, the design will be considered to have +_conditionally_ passed. This will allow the design to move forward in +the RISC-V Compatible listing process. For flawed-test waivers, once a +replacement test is available, the design will need to be retested and +must pass all tests to change the _conditional pass_ to a _pass_. If the +test continues to fail, then it is an errata and subject to the +errata-based waiver process. + +All waivers must be approved by a majority vote of the appropriate ISA +Committee (i.e., privileged or unprivileged) and the SW or other related +non-ISA HC.. + +==== Test Case Failures due to ISA restrictions or ambiguity + +If a design fails on a test case, and the implementer believes that the +failure is due to either an ambiguity in the ISA or that the ISA is +inappropriately restrictive in the allowed behavior, the implementer +should make a request to the appropriate ISA Committee to have the +architecture amended. No waivers will be granted for such a case. +However, if the architecture is subsequently changed, the appropriate +tests will also be changed. + +It is important to keep in mind that changes to the semantics of the ISA +must go through the entire ratification process. Clarifications to the +ISA that don’t change the semantics are subject to a lighter-weight +process that is beyond the scope of this document. + +[NOTE] +==== +Architectural Ambiguity cases are very sensitive; if unintended behavior +is allowed it might result in fragmentation of the architecture. These +cases must undergo the utmost scrutiny by appropriate experts to avoid +any unintended consequences. + +It is incumbent upon the implementer to run the ACT early enough in the +design process so that any failures can be investigated and design +changes incorporated. Likewise, any issues with the tests, including +unexpected results from the reference design (especially in the case +where more than one result can be considered correct) need to be brought +to the attention of the appropriate ISA Committee as soon as possible. +That said, the implementer needs to have performed enough verification +on the design before attempting to run the ACT, such that the ACT is not +used to find bugs. The rationale here is the ACT is a spot check +intended to find major flaws in a verified design; any failures in the +ACT point to a major gap in the understanding of the architecture or the +design verification process. +==== + +=== Exceptions + +Exceptions to the test requirements are handled through the waiver +process and changes to the ISA as mentioned above. + +Implementers releasing non-standard extensions must label them as "X" +extensions as per the unprivileged specification and even though they +may fully pass ACT, any support for software ecosystem components will +be only supported through vendor efforts and not through RISC-V. + +Any escalation should occur to the CTO who may choose to resolve the +issue, or escalate to the TSC or the CEO or the BOD. + diff --git a/src/act_priv_spec_1_11.adoc b/src/act_priv_spec_1_11.adoc new file mode 100644 index 0000000..30289d4 --- /dev/null +++ b/src/act_priv_spec_1_11.adoc @@ -0,0 +1,73 @@ +[[act_priv_spec_1_11]] +== ACT Requirements for Privileged 1.11 Specification + +*Version:* 0.2 + +*One line description:* This policy describes simplified Architectural +Compatibility Test (ACT) requirements for the privileged specification. +This policy is temporary and will be replaced by a standard ACT suite in +the future. + +*Author(s):* Greg Favor, Arun Thomas + +*Status:* Archived + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|0.2 |2022-01-13 |added clarity on system emulators |Greg Favor +| |2021-09-02 |added clarity on ACT vs compatibility testing. | + +|0.1 |2021-05-03 |Original draft |Greg Favor, Arun Thomas +|=== + +=== Rationale + +https://docs.google.com/document/u/2/d/1ZKSLQ5HPT3E_CqTVOQlBPs7qJ9v1mpnMDXHhtOQJFcU/edit[Architectural +Compatibility Tests (ACT)] are required for Privileged Specification +v1.12 ratification. As there is no current ACT suite for Privileged +Specification v1.11 (let alone v1.12) and there is no plan to develop +them in time for ratification, this policy proposes an alternate +compatibility testing methodology based on running operating system and +hypervisor software that exercises new features added in Privileged +Specification 1.12. + +=== Policy: + +. In lieu of member’s running ACT suite for Privileged Specification +1.12 features which are intended to be used for compatibility, +implementations must run an operating system and hypervisor software (or +equivalent) using the extensions as a prerequisite to claim +compatibility with Privileged Specification 1.12. + +. TGs will not be required to develop ACT tests in order to pass +https://docs.google.com/document/u/2/d/1Hp9ZZSzjk6Tp2pIvh33mNCj6wAoJCEqsdENQUTSruQg/edit[DoD] +in 2021. + +. RISC-V International will provide OS and hypervisor patches that add +functionality for new Privileged Specification 1.12 features to be +exercised, including stc, Sccofpmf, Svnapot, Svinval, Svpbmt, Sv57, and +the H extension. For OS compatibility testing, RVI will provide Linux +kernel patches adding support for Privileged Specification 1.12. For +hypervisor compatibility testing, RVI will provide KVM and Xvisor +patches adding support for Privileged Specification 1.12. As there is +upstream Linux kernel support for Privileged Specification 1.11, no +additional patches will be required for Privileged specification 1.11 +features. + +. To demonstrate compatibility, a compatible implementation must: + +.. Boot a Linux distribution and run simple commands and small +benchmarks. + +.. Boot a Linux distribution and run simple commands and small +benchmarks in a virtual environment running on KVM. + +.. Boot a Linux distribution and run simple commands and small +benchmarks in a virtual environment running on Xvisor. + +. For practical runtime considerations, this is expected to be done on +either an FPGA, FPGA prototyping system, or emulation system (e.g. a +supported simulator). + +. One may shortcut the boot process wrt time-intensive steps that +repetitively perform an operation and do very little to utilize +significant Privileged specification features or exercise architectural +corner cases. + +. This policy is temporary and applies only to Privileged Specification +1.12 ratification. + +=== Transition to start using policy: + +Immediate diff --git a/src/approved.adoc b/src/approved.adoc deleted file mode 100644 index ed0fe75..0000000 --- a/src/approved.adoc +++ /dev/null @@ -1,5 +0,0 @@ -== Approved Policies - -Policies in this section have been approved. - -include::technical_voting.adoc[] diff --git a/src/architecture_review.adoc b/src/architecture_review.adoc new file mode 100644 index 0000000..47a1f7a --- /dev/null +++ b/src/architecture_review.adoc @@ -0,0 +1,114 @@ +[[architecture_review]] +== Architecture Review + +*Version:* 1.2 + +*One line description:* This policy cover the opcode encoding, mnemonics, and CSR + +*Author(s):* Greg Favor, Krste Asanović + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.2 |2024-01-16 |Change escalation path to occur through CTO |Greg Favor + +|1.1 |2021-10-20 |Update email for reviews to be submitted |Stephano Cetola + +|1.0 |2021-05-17 |Policy approved by TSC - 10 approve 0 abstain 0 object |Stephano Cetola + +|=== + +=== Rationale + +We need to produce robust extensions that are consistent with the ratified RISC-V specifications and RISC-V overall strategy. + +We also need to coordinate assignments of opcode encodings, mnemonics, +CSRs, etc so we have a consistent set of conventions across extensions, +handle different profile targets, and manage encoding resources. + +=== Policy + +There was a previous policy that covered some of the same areas as this +policy and this policy fully supersedes any older policy covering the +same topics. + +The Architecture Review policy and process will be managed and performed +by the Unprivileged and Privileged ISA committees (ICs). This will be +structured in a way to enable parallel work by several key architecture +people. Responsiveness as well as sufficient thoroughness are both +goals. + +There are four pieces to this process: + +* Architecture review of Unpriv extensions by the Unpriv IC + +* Architecture review of Priv extensions by the Priv IC + +* Opcode assignment review + +* CSR assignment review + +==== Process details + +* The four ISA committee chairs and their delegates, will work together +to accomplish this policy. + +* Architecture reviews will examine the architectural consistency, +cost/benefit justifications, and specifics of an extension as being +appropriate for standardization by RISC-V (e.g. are there questionable +details, potentially unjustified features, or architectural choices +inconsistent with the overall RISC-V architecture). This doesn’t +supplant the need for Task groups (TGs) to do their full diligence as +part of developing a proposed architecture extension. The more +thoroughly a TG does its work and documents, the what and why, the more +smoothly the review process will go and it will help the overall +extension development process produce quality RISC-V architecture +extensions. + +* The chairs will delegate who will drive CSR assignment review (as +technically the most appropriate people to do this knowledgeably and +holistically). + +* Opcode assignment review will be handled more dynamically and jointly +between the IC chairs and their delegates. + +* The DoD sign-offs for the ICs will be contingent on completing this +policy for each extension. + +* The definition of done (DoD) checklist deliverables concerning early +opcode assignments, etc. will be conducted in accordance with this +policy and must be completed in time for the appropriate DoD +milestone. + +* The mailto:tech-arch-review@lists.riscv.org%20[tech-arch-review] email +list is the one portal for submissions from TGs of arch extensions to be +reviewed. This also includes submissions for preliminary reviews of +specific key issues or questions. An updated version of the submission +status spreadsheet will have tracking/status columns for the above four +pieces. (The intent is to try and provide opcode and CSR assignment +feedback, when possible, more quickly and ahead of complete arch review +feedback.). The queue will be reviewed by one of the chairs of the ICs +at every chairs meeting and rolled up to the BOD monthly for the high +priority extensions. + +==== AR Review During the Specification Development Lifecycle + +In the process of developing the RISC-V Specification, Architecture +Review (AR) serves a pivotal function. This review can occur at various +stages: Planning, Development, Freeze, and Ratification-Ready. + +During the Planning and Development phases, AR functions primarily as a +consultative activity, offering requested guidance on possible architectural +choices and suggestions for improvement. However, the Architecture Review conducted +during the Freeze stage is particularly important and mandatory, as it determines +whether the specification is genuinely prepared to advance or if modifications +and enhancements are needed. Lastly, AR is required during the Ratification-Ready +phase if the specification text has undergone any significant changes (i.e. past +simple typo corrections, formatting corrections, and very simple clarifications). + +=== Exception handling + +All exception requests should be forwarded to the ISA committees. It is +unlikely any will be granted. + +Any escalation should occur to the CTO who may choose to resolve the +issue, or escalate to the TSC or the CEO or the BOD. + +=== Transition to start using policy + +Effective immediately. This will be the acting policy while awaiting +approval (possibly with modifications before approval). Any extension +that was part way through the process with the previous policy should +contact the ISA chairs to determine how to proceed. diff --git a/src/ccm_guest_policy.adoc b/src/ccm_guest_policy.adoc new file mode 100644 index 0000000..b45b54b --- /dev/null +++ b/src/ccm_guest_policy.adoc @@ -0,0 +1,76 @@ +[[ccm_guest_policy]] +== Committee Chair Meeting (CCM) Guests + +*Version:* 1.1 + +*One line description:* Under what circumstances do we allow/ask guests to join CCM + +*Author(s):* Mark Himelstein, Stephano Cetola + +*Status:* Approved + + +*Version History:* + + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.1 |2022-05-10 |Add text regarding stand-in or substitute attendees to the CCM. |Stephano Cetola + +|1.0 |2021-10-06 |Initial commit. |Mark Himelstein + +|=== + +=== Rationale + +Numerous members have asked to present or attend the CCM who are not +committee chairs or Premier members or Premier TSC members. In order to +be fair about who gets to visit, when they get to visit, what part of +the meeting they can attend, and the process for such requests, we +developed this policy. + +=== Policy + +. Guests may request to present to the CCM by approaching a member of +the CCM and asking them to sponsor the presentation. Guests who don’t +know who to use as a sponsor, may use the CTO as a sponsor. + +. The sponsor should review the presentation. If the sponsor agrees to +having the CCM see the presentation, then they forward the request with +slides to the CCM email list for review. + +. During the review period CCM members may reply to the email with +issues, questions, or objections. + +. The TSC chair and CTO jointly make a final decision as to whether to +approve a presentation. + +. If the CTO or the TSC chair are the sponsor for the guest, the TSC +vice chair will participate with the other non-sponsor (CTO or TSC +chair) to make the final decision as to whether to approve a +presentation. + +. If there are no objections and the questions and issues are resolved, +the guest will have an up to 30 minute slot at the meeting following the +2 week review period. + +. Guests who present may only attend the CCM for the duration of their +presentation. + +. Guests may bring one extra person to help make the presentation. + +. CCM will allow 2 guests/presentations maximum per meeting + +. The sponsor can work with the CTO & TSC Chair if more than 30 minutes +is needed. + +. The CCM may ask questions of the guest during the meeting and conduct +a dialog, but this is intended as a technical discussion regarding the +merits of the topic/proposal and not a strategic discussion about RISC-V +strategy, vision, or priorities. + +. Any discussions amongst the CCM resulting from the presentation must +occur after the guest has left the meeting. This privilege is reserved +for Premier members, Premier TSC members, and committee chairs. Allowing +others in those conversations dilutes the value of membership levels. +Guests are not permitted to join the general CCM for the same reasons. + +. If any regular member of the CCM is not able to attend a meeting, they +may designate a stand-in. That substitute cannot vote, but can attend +the meeting and participate in discussions. + +=== Exception handling +For any escalations about guests being turned down (either by the +sponsor or by the CCM), please contact the CTO. + +The TSC chair and CTO may jointly ask a guest to join a non-presentation +conversation if they feel the member is needed to conduct the +conversation. Guests may not request this. + +=== Transition to start using policy +Immediate + diff --git a/src/chairs_best_practices.adoc b/src/chairs_best_practices.adoc new file mode 100644 index 0000000..b403821 --- /dev/null +++ b/src/chairs_best_practices.adoc @@ -0,0 +1,233 @@ +[[chairs_best_practices]] +== Chairs Best Practices + +*Version:* 1.5 + +*One line description:* Guidance on practices if you are a chair or vice-chair + +*Author(s):* Charlie Su, Mark Himelstein, Jeff Scheel + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.5 |2024-04-17 |Use U.S. Pacific Time as reference |Jeff Scheel + +|1.4 |2022-03-31 |Add a calendar scheduling tip. |Jeff Scheel + +|1.3 |2022-02-18 |Reference Encumbered information policy for new Chairs |Jeff Scheel + +|1.2 |2021-09-24 |Added information for new Chairs. Simplified handling +of inappropriate behavior. |Jeff Scheel + +|=== + +=== Rationale + +Chairs may or may not have had experience running a group in an Open +Source community or with broad company and geographical diversity. This +policy provides best practices. These are not rules. Take what works and +leave the rest. + +=== Related documentation + +* https://docs.google.com/presentation/d/1eEVuu6lRZd9iiDnZQSZME7Q7svtTG3pGIKHPmZ79B8E/[RISC-V +Technical Organization] + +* https://docs.google.com/presentation/d/1LNhpuNwU54TgwGfcl-Fgf4HUFxCxh0AztPaeqMuRQRw/edit?usp=sharing[Common +disclaimer slides] + +* https://docs.google.com/document/d/1f19w2a0lnW9VaXKHfKy84Ov54vfVrc35hibNDZ_t38I/edit?usp=sharing[Getting +Started Guide] + +* https://docs.google.com/document/d/1TdUWp-OUIQjsWgip7bRfhZBuUC64Upf5eyfBj7fWd_Q/edit?usp=sharing[Github +Policy] + +* https://riscv.org/community/community-code-of-conduct/[Code of +Conduct] + +* https://docs.google.com/document/d/1dE_4K0kiQLPrwnf1avAWYSpaSpznrrEydobVYzJybu0/[Encumbered +Information policy] + +* https://docs.google.com/document/d/1Hp9ZZSzjk6Tp2pIvh33mNCj6wAoJCEqsdENQUTSruQg/[Definition +of Done policy] + +* https://docs.google.com/spreadsheets/d/1qzu6b9kgADGjaa5fd1Qla7b9gCMOaEnGO5bUVu2oPys/[Status +spreadsheet] + +* https://jira.riscv.org/secure/Dashboard.jspa[RISC-V Jira Dashboard] + +=== Policy + +==== Getting started + +* Familiarize yourself with the +https://docs.google.com/presentation/d/1eEVuu6lRZd9iiDnZQSZME7Q7svtTG3pGIKHPmZ79B8E/[RISC-V +technical organizational structure], the various group types and areas +of work. + +* Review and understand the +https://docs.google.com/document/d/1dE_4K0kiQLPrwnf1avAWYSpaSpznrrEydobVYzJybu0/[Encumbered +Information policy] before you have your first meeting. + +* Work with the Technical Project Managers (TPMs) (help@riscv.org) to +have your community mailing list created (Groups.IO) and community +documents repository (GitHub) setup +** Ensure you are a moderator in the group, contact help@riscv.org if +you are not. + +** Provide your GitHub id to TPMs and accept the invitation to be an +Admin to the repository + +* Lead a discussion on the community mailing list (setup above) about +when to hold the first meeting and schedule it. Ask help@riscv.org with +running a survey if needed. + +* Lead first meeting with an agenda like the following: +** https://docs.google.com/presentation/d/1LNhpuNwU54TgwGfcl-Fgf4HUFxCxh0AztPaeqMuRQRw/edit?usp=sharing[Disclaimer +slides] (used at all meetings) + +** Self-introduction of all attendees - name, company, experience, +interest in group + +** Discussion about meeting frequency and timing + +** Charter review, discussion, and updates. Typically, the group +sponsor (Technical Steering Committee [TSC], Horizontal Committee [HC], +ISA Committee [IC], or Horizontal Sub-Committee [HSC]) provides a draft +charter statement. The goal is to have a written Charter.md file in your +GitHub repo home directory that will be approved by your sponsors. +*** A good Task Group (TG) charter describes how it achieves filling in +a gap defined by the Special Interest Group (SIG) or Committee that +spawned it (directly or dotted line). It lists the specific small set of +deliverables it will deliver. + +*** A SIG is an extension of a Committee, in that its only deliverables +are strategy, gaps, and prioritizations, and helping spawn other SIGs or +TGs to fill the gaps. A good SIG charter spells out the small set of +topic areas their strategy will address along with its responsibilities +as laid out in this bullet. + +* Lead the next few working meetings focused on reviewing and refining +the charter and gaps in your strategic area. +** Be sure to review the Charter drafts with the RISC-V CTO and your +sponsoring Chair and Vice-chair to get their feedback. + +** If you are a SIG, document your gap analysis in another document and +retain it in your GitHub repo so that you can re-visit and update as +needed in the future. Ensure that your charter provides a vision for how +gaps may be addressed. + +** When your charter is defined and stable, your sponsoring Chair and +Vice-chair will help seek approval. + +* https://docs.google.com/document/d/14ZpciYwIzmuiB92_hKfwTAttTnc3rsLbWI-CpC7MdC8/edit?usp=sharing[Acting +chair and/or vice chair] should work with their group to elect permanent +leadership, which may be the acting chair/vice chair. + +* Once the formal (non-acting) Chair and Vice-chair are elected, and +the Charter is approved, the group should work towards completing the +https://docs.google.com/presentation/u/2/d/1nQ5uFb39KA6gvUi5SReWfIQSiRN7hp6z7ZPfctE4mKk/edit[plan +milestone] for the +https://docs.google.com/document/u/2/d/1Hp9ZZSzjk6Tp2pIvh33mNCj6wAoJCEqsdENQUTSruQg/edit[definition +of done]. + + +==== Regular group meetings + +* Do as much in email without meetings as you can +** Take items offline as appropriate + +** Conduct discussions on the group’s email list. Spec issues go in +github issues. Cross group things go in +https://jira.riscv.org/secure/Dashboard.jspa[Jira]. + +* Groups or Committees that are active and producing work product +(specs, etc.) should hold meetings periodically (at least once every 1-3 +months) as appropriate. + +* Schedule and host virtual meetings + +* Use the United States Pacific Time as the timezone for scheduling all +meetings. By everyone uses this as the base time zone for their +meetings, relative meeting times among different meetings won’t +inadvertently drift either. + +* Display the +https://docs.google.com/presentation/d/1LNhpuNwU54TgwGfcl-Fgf4HUFxCxh0AztPaeqMuRQRw/edit?usp=sharing[common +disclaimer slides] at all meetings. If you want them included in your +agenda slides please use links (option when you paste in google slides) +so you always have the latest. + +* Be respectful of different time-zones and cultures and companies and +countries when scheduling or running meetings. + +* Repeat questions when answers are given + +* Notify attendees that only members are allowed in meetings. Ask that +non-members please exit the meeting. It is not your job to enforce the +rules. If there is someone you don’t believe belongs there send email to +help@riscv.org. + +* Ask everyone to have identifiable names (first and last name and +company/individual) when logging into zoom + +* Use RISC-V tools (zoom, github, calendar) + +* Send meeting agendas at least two days in advance. Ask for items +members would like to add to the agenda + +* Pass down messages from chairs or TSC meetings + +* https://docs.google.com/document/d/1TdUWp-OUIQjsWgip7bRfhZBuUC64Upf5eyfBj7fWd_Q/edit?usp=sharing[Record, +send, and archive meeting minutes] + +* keep up-to-date with chair meeting agendas and notes + +* If anyone is saying something inappropriate, +** State that the behavior is inconsistent with the RISC-V +https://riscv.org/community/community-code-of-conduct/[Code of Conduct] +and ask them to stop. If the behavior has occurred via email, use +reply-all for your request. + +** To continue activity and model the proper behavior, redirect the +conversation back to the issue at hand. + +** If the inappropriate behavior re-occurs in a meeting, adjourn it. + +** Report the incident to either help@riscv.org or to the code of +conduct email, conduct@riscv.org. + + +==== Ongoing tasks + +* *Manage extension/feature lifecycle. This should be the highest +priority* +** include work relating to drafts, change rationale, change control, +definition of done, etc. + +** optimize the delivery of useful specs. + +* Attend regular Chairs Meetings (& TSC meetings if appropriate) + +* Attend the sponsoring committee meetings and work with the Chairs and +Vice-chairs to deliver on their responsibilities and charter as well as +updating them on your group’s progress + +* Raise blockers to Chairs Meeting promptly + +* Work with sponsoring Chair and Vice-chair to address technical +blockers + +* Address questions posed to the group with at least some SLA +** E.g. "the answer will be next week" or "we decided not to address +this now" + +* Interact with other teams based on org chart and +https://docs.google.com/document/d/1Hp9ZZSzjk6Tp2pIvh33mNCj6wAoJCEqsdENQUTSruQg/[Definition +of Done] (be prepared for sign-offs -- don’t make the sign-off the first +discussion you have with the other committees) + +* Update monthly the +https://docs.google.com/spreadsheets/d/1qzu6b9kgADGjaa5fd1Qla7b9gCMOaEnGO5bUVu2oPys/[Status +spreadsheet] +** Include dates, specs, accomplishments, issues, resources needed, new +extension names, etc. on "ratification package" tab, columns marked +"Fill These in Monthly Please" + +** Request help from DevPartners by adding rows to the "development +partners" tab. Put in as much as you can, especially the name of the +technical person from the group who will be overseeing the work with the +DevPartner (column marked "RISC-V liaison") + + +==== Evangelism + +* Grow partners and/or members for the group. If you identify people or +entities that should be involved but are not and you don’t how to reach +out to them, send email to help@riscv.org + +* Provide SWOT (strengths, weakness, opportunities and threats) +analysis and promotion plan for the group technologies + + +==== Other activities + +* Promote the groups’ technologies in conferences and seminars + +* Recognize that there are two logical roles for each group: +logistical/administrative lead, and technical lead. Try to play to +people’s strengths and interests. If you are missing someone to play one +of these roles and don’t know how to fill it, please send email to +help@riscv.org + +* Leave marketing and PR to the marketing team. If you have something +you need them to pay attention to, please send an email to +help@riscv.org. + +* Groups should publish the links to charter, specs and various +documents according to the best practices and +https://docs.google.com/document/d/1TdUWp-OUIQjsWgip7bRfhZBuUC64Upf5eyfBj7fWd_Q/edit?usp=sharing[Github +Policy] and go into the appropriate repo (technical group vs spec vs +upstream, etc.). + +* Groups should use github issues and Jira as described in the +https://docs.google.com/document/d/1f19w2a0lnW9VaXKHfKy84Ov54vfVrc35hibNDZ_t38I/edit?usp=sharing[Getting +Started Guide]. + +* Remember that we as engineers often side on being critical thinkers +and listeners. Please remember to thank and acknowledge the effort of +members even if their effort needs more work. + +If you have any questions please ask for a meeting regarding this policy +to help@riscv.org. + +=== Transition to start using policy + +Active as of now as it is only advice + +=== Exceptions + +Not applicable + diff --git a/src/chapter2.adoc b/src/chapter2.adoc deleted file mode 100644 index 856334b..0000000 --- a/src/chapter2.adoc +++ /dev/null @@ -1,48 +0,0 @@ -[[chapter2]] -== The Second Chapter - -. The first item. - -. The second item. -+ -.. The first sub item. - -.. The second sub item. -+ -[CAUTION] -==== -A moment of caution is required for this block of text must be read and apreciated for its importance. -==== - -. Yet another item. - -. Again, an item. - -.. A multi-line item. -+ -This item has multiple lines. -+ -By multiple lines, this is what we mean. -+ -Seriously, multiple. - -=== An example table - -.Nonsensical table -[cols="^1,^1,^1,^1,^3,^3",stripes=even,options="header"] -|=== -4+|Letters _and_ bits {set:cellbgcolor:green} 2+|A much longer area -|L|R|W|X|Quarter 1|Quarter 2 -|{set:cellbgcolor:!} 0|0|0|0 2+|Rows alternate colors -|0|0|0|1|Thing 1|Thing 2 -|1|0|0|0|Thing 3|Thing 4 -|1|1|1|1 2+|Span Thing 1 and 2 -|=== - -=== Sub section - -Diam donec adipiscing tristique risus indexterm:[risus]. Nisl rhoncus mattis rhoncus urna. Egestas egestas fringilla phasellus faucibus scelerisque eleifend donec pretium vulputate. Porta non pulvinar neque laoreet suspendisse interdum consectetur libero id. Massa vitae tortor condimentum lacinia quis vel. Donec ac odio tempor orci. Mi sit amet mauris commodo quis imperdiet massa tincidunt. Quis enim lobortis scelerisque fermentum dui. Lacus viverra vitae congue eu. Sed faucibus turpis in eu mi bibendum neque. Sit amet porttitor eget dolor. Aliquet eget sit amet tellus cras adipiscing enim. Id cursus metus aliquam eleifend mi. Vestibulum lorem sed risus ultricies tristique nulla aliquet. - -=== Yet another subsection - -Quam lacus suspendisse faucibus interdum posuere lorem ipsum. Nulla aliquet enim tortor at auctor urna nunc id cursus. Massa massa ultricies mi quis hendrerit dolor magna. Integer enim neque volutpat ac tincidunt. Dolor magna eget est lorem ipsum dolor. Urna neque viverra justo nec. Neque gravida in fermentum et. Fringilla ut morbi tincidunt augue interdum velit euismod. Dolor sit amet consectetur adipiscing elit. Eu facilisis sed odio morbi. In cursus turpis massa tincidunt dui. Orci indexterm:[orci] phasellus egestas tellus rutrum tellus. Semper eget duis at tellus at urna condimentum. Orci porta non pulvinar neque laoreet suspendisse interdum consectetur. diff --git a/src/contributors.adoc b/src/contributors.adoc index 13fd776..6ccff93 100644 --- a/src/contributors.adoc +++ b/src/contributors.adoc @@ -3,5 +3,19 @@ This RISC-V specification has been contributed to directly or indirectly by: [%hardbreaks] -* Author1 -* Author2 +* Allen Baum +* Arun Thomas +* Charlie Su +* Ed Jones +* Gajinder Panesar +* Greg Favor +* Jeff Scheel +* Jeremy Bennett +* Ken Dockser +* Krste Asanović +* Mark Himelstein +* Nidal Faour +* Philipp Tomsich +* Rafael Sens +* Stephano Cetola +* Tariq Kurd diff --git a/src/dev_partner.adoc b/src/dev_partner.adoc new file mode 100644 index 0000000..92e807b --- /dev/null +++ b/src/dev_partner.adoc @@ -0,0 +1,130 @@ +[[dev_partner]] +== Development Partner Model + +*Version:* 1.1 + +*One line description:* Process and policies regarding being a development +partner and doing projects to help Task Groups complete DoD tasks for +public review and ratification + +*Author(s):* Mark Himelstein + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.1 |2021-02-02 + +a| Updates: + +. Requiring Development Partner to be able to do 3 medium sized project +simultaneously + +. SOW & Status folder, README, templates + +. Approval process to initiate a Development Partner project. + +|Mark Himelstein + +|1.0 |2020-11-25 |Original version | Mark Himelstein + +|=== + +=== Rationale + +We are starting to work with Development Partners (i.e. institutions or +groups that are volunteering to take on Development tasks for RISC-V +TGs). + +We developed this Model so that we could get help for architects working +on RISC-V projects requiring their skills who may be spending their time +instead both architecting and delivering Ecosystem components that could +be done by non-architect level Developments. In this way architects +could spend their time on architecture and help get the extensions and +work products finished. + +We also have accumulated technical debt (i.e. things we did not do -- +for example we did not do the architecture tests for floating point when +we ratified the extension). This model will also be used to address the +technical debt. + +=== Policy + +Ramp project to on board get a Development Partner productive : + +. RISC-V folks pick a ramp project. This should be a project where the +initial results can be visible in a month (not including holidays). When +we make enough progress to know we are being productive, we can expand +the work to include more projects. + +==== General process + +. The RISC-V group driving the work (IC, HC, HSC, or TG) picks a liaison +to work with the Development Partner. + +. Development Partner picks a non-student liaison to work with RISC-V. + +. Liaisons should be both technically and organizationally capable + +. While RISC-V TGs have oversight, the liaisons will be the main point +of interaction. This is done to minimize the impact on the RISC-V +architects and ensure that RISC-V architects are not managing the +Development Partner Developments directly. The hope is that we can have +one liaison from each organization but there may have to be more +depending on the variation in project skills and areas needed. If we +have more than one liaison, we will pick a primary one from RISC-V and +the Development Partner to coordinate across a number of projects and +liaisons as appropriate. + +. The SOW and status are stored on the shared drive +https://drive.google.com/drive/folders/1x5gzhPtKqcHFgX8t3h55qSsKhDkIOCMJ?usp=sharing[here] +and the +https://docs.google.com/document/d/1zyrpBB-EzXcJj7UuGQhnIfFyKRav0z2GyPyTRf-bjOM/edit?usp=sharing[README] +in that directory has conventions including templates for the SOW and +status. + +. RISC-V will provide the following initial deliverables to start a +project: requirements, deliverables, and acceptance criteria which make +up the SOW. For a small project this should all fit on one page. An +example of acceptance criteria in the industry from the GNU toolchain is +available +https://www.google.com/url?q=https://docs.google.com/document/d/1Eio39QTHNM9Lmi1VXoH7PYLgBGUscvpdPxB6YmZonVk&sa=D&source=editors&ust=1612297663762000&usg=AOvVaw1KGxbfwRv1tCPTsd_fuiei[here]. + +. Once you develop a SOW, the liaison sends an email to the +cto-group-contributor lists.riscv.org email group asking for a resource +and places the task in the status spreadsheet tab used to identify tasks +you need resource help with. Please do not approach Development Partners +yourself as the TSC has set priorities and we are working to address +their priorities first. + +. The Development Partner and RISC-V will review the RISC-V initial +deliverables until both teams feel the Development Partner understands +the task and has the beginnings of a plan to get the work done as per +the requirements. + +. Regular status is due monthly and will be reported to the appropriate +groups (chairs, BOD, etc.). There is a self-serve +https://docs.google.com/spreadsheets/d/1qzu6b9kgADGjaa5fd1Qla7b9gCMOaEnGO5bUVu2oPys/edit?usp=sharing[status +spreadsheet] on the shared drive in the status folder with a projects +tab where we will track progress rollup. The full report is in the +directory specified above. + +. The RISC-V liaison will drive the review of deliverables and adherence +to acceptance criteria with the RISC-V TG and work with the Development +Partner liaison to resolve any issues. + +. The following skillsets are needed: + +.. Formal model (SAIL) + +.. Architecture tests (ISA, assembler) + +.. Toolchain support (GCC, LLVM, debugger, profiler, …) + +.. Simulators (SPIKE, QEMU, SAIL generated, …) + +.. Hypervisors (KVM, etc.) + +.. Operating Systems (both Linux like and RTOS like) + +.. Library support (e.g. crypto libs, npi libs, ml libs, java runtime, +…) + +.. Prototyping (FPGA, simulator, RTL, etc.) + +.. Documentation + +. A Development Partner should be able to support a minimum of 3 medium +sized projects simultaneously after the proof of concept project. It +takes effort to spin up a Development Partner and we would like to +leverage that effort on the RISC-V side). + +. Development Partners should have approximately 1 non-student +manager/project leader per 15 students or junior Developments maximum +(so a big project may need both a liaison and some managers). + +=== Exception handling + +Not applicable + +=== Transition to start using policy + +Immediately + diff --git a/src/ecosystem_labs.adoc b/src/ecosystem_labs.adoc new file mode 100644 index 0000000..292b632 --- /dev/null +++ b/src/ecosystem_labs.adoc @@ -0,0 +1,142 @@ +[[ecosystem_labs]] +== Ecosystem Labs + +*Version:* 1.2 + +*One line description:* processes and policies regarding being a RISC-V Ecosystem Lab + +*Author(s):* Mark Himelstein, Jeff Scheel + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.2 |2024-08-21 |Rename to “Ecosystem Labs”, not just “Labs” to avoid confusion with future CSC Labs |Jeff Scheel + +|1.1 |2024-03-08 |Recommend including SLA in on-boarding process |Jeff Scheel + +|1.0 |2023-02-14 |Approved version |Jeff Scheel + +|0.4 |2023-02-06 |Final edits for CTO approval |Jeff Scheel + +|0.3 |2022-11-10 |Proposal version to Tech Chairs |Jeff Scheel + +|0.2 |2022-03-24 |Additional granularity of Labs definition and +requirements. Allow for self-defined capacity and SLA. |Jeff Scheel + +|0.1 |2021-04-27 |Original draft |Mark Himelstein + +|=== + +=== Rationale + +The main goal of the RISC-V Ecosystem Labs program is to make RISC-V successful, +either as a vendor or industry proponent, through the following +contributions: + +* Finding software regressions early for the whole community + +* Increasing RISC-V recognition and public-relations + +* Engaging open source communities to bring in new workloads, etc. + +* Broadening the set of RISC-V platforms available for testing and +improving the hardware and software ecosystem + +* Testing RISC-V hardware earlier and more broadly + +* Growing the RISC-V community by providing RISC-V machines for +developers and researchers. + +* Connecting RISC-V Labs with vendors to provide early hardware access + +=== Policy + +RISC-V Ecosystem Labs offer one or more of the following: + +. Continuous Integration (CI) testing of RISC-V software (see +https://docs.google.com/spreadsheets/d/1JENqHLyrfDStluwkz80rseNrA-qeSf2hVuiE2_Bucr4/[CI +Testing spreadsheet], "Test Matrix" tab) for a portion of the "Test +Matrix" with flexibility to constrain the focus into a subset of Test +Suites, Boards, or Specific Components. + +[NOTE] +CI may be a Lab commitment of coverage to RISC-V or a service +provided to external users in the broader community. + +. Sandbox access of RISC-V platforms to external users of the following +types: + +.. Bare-metal servers + +.. Containers + +.. Native virtual machines (KVM on RISC-V) + +.. Specialized hardware configurations such as HPC clusters, FPGA farm, +IOT + +To become a RISC-V Ecosystem Lab, all of the following requirements must be met: + +* Join and participate in the RISC-V Labs community +(https://lists.riscv.org/g/lab-partners[lab-partners]) community + +* Have at least 10 physical machines/boards or 20 physical cores of +RISC-V hardware as resources for the Labs. + +* Implement a Labs solution/service (CI and/or Sandbox) with +consideration of the best-practices and software frameworks of the +RISC-V Labs community +(https://lists.riscv.org/g/lab-partners[lab-partners]) community. +Contribute to and improve such practices as-needed. + +* If you are providing an external service, on a best-effort basis, +address on-going capacity requirements through the following steps: + +. Publish to the user(s) the complete list of resources (systems, cpus, +memory, storage, networking) available for use and for which service (CI +or Sandbox) + +. Define a set of metrics which will be monitored to determine resource +utilization. + +. Regularly report status of the capacity utilization to the Lab +Partners group. + +. Evaluate resource additions as needs require and new platforms become +available. + +* If you are providing an external service, on a best-effort basis, +address service guidelines as follows: + +. Provide a written policy for use of the resources. This policy should +address data retention, privacy, intellectual property, security, usage +restrictions, and other areas which may need to be addressed per +geographic location. + +. Publish a Service Level Agreement (SLA) for current and future +users. + +[NOTE] +It is strongly encouraged to ensure the SLA is included as part of the application or on-boarding process for projects. + +. Define a set of metrics which will be monitored to track SLA +performance + +. Regularly report status of the SLA metrics to the Lab Partners +group. + +. Build and execute action plans as needed to address gaps in SLA + +* Create and maintain a web presence for the Lab that provides the above +information as well as providing additional mission information and a +description of how to gain/request access. + +* Report Lab status for the capacity utilization, SLA metrics, and/or CI +Results (when applicable) to the Lab Partners working group at regular +intervals (quarterly) + +* Publish all report status information in the Google Drive for risc-v +members -> Status -> Labs Google folder or other public location as +defined by the Lab Partners working group. + +* Maintain a public, real-time status information via the web, e.g. a +"dashboard" + +* Self-manage the capacity requirements and the SLA on an honor system +("best effort") basis. + +* Perform triage (not full diagnosis) on failures. + +* Provide a means for users to submit and track issues (JIRAs or +GitHub). + +Once a RISC-V Ecosystem Lab can demonstrate compliance with the above requirements +for 2 consecutive quarters, they can submit a formal request via email +with documentation which demonstrates completion of the criteria to +become a RISC-V Lab (help@riscv.org). Once the RISC-V program has +reviewed and approved the request, the organization logo will be +displayed on the Labs program page (TBD, but similar to the RISC-V +https://riscv.org/risc-v-development-partner/[DevPartners page]) of the +RISC-V website (https://riscv.org[riscv.org]). + +If an approved Lab fails to continue to meet the criteria, they will be +informed of their gap in writing and allowed 90 days to comply. Failure +to comply by the correction deadline will result in their approval being +revoked in writing and from their logo being removed from the program +page. + +=== Exception handling + +If you have problems with implementing any of this, you should send an +email to help@riscv.org. + +=== Transition to start using policy + +Immediately upon approval + diff --git a/src/encumbered_info.adoc b/src/encumbered_info.adoc new file mode 100644 index 0000000..faefd1f --- /dev/null +++ b/src/encumbered_info.adoc @@ -0,0 +1,80 @@ +[[encumbered_info]] +== Encumbered Information + +*Version:* 1.3 + +*One line description:* When and why you can or cannot discuss or +reference encumbered information + +*Author(s):* Mark I Himelstein + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.3 |2022-02-28 |Comment acceptance and updates for clarity. Add +version history. |Jeff Scheel + +|1.2 |2021-05-06 |Moved venue earlier so it can be used and used it in +the item starting with "never discuss" Clarified some of the review +process policy item |Mark Himelstein + +|=== + +=== Rationale + + +Create a clear and definitive set of guidelines for how and when you can and cannot discuss or reference encumbered information. Policy: + +. Encumbered information can have a wide set of definitions and +instances. This policy may apply to situations where it appears that a +good faith mistake may have been made around the sensitivity or +licensing status of materials present in a RISC-V hosted location. If +you have a question about whether something is encumbered, please send +an email to help@riscv.org to set up a meeting to discuss the specifics. +If you are unsure, consider the information encumbered until you know +otherwise. + +. The word "venue" used below refers to RISC-V emails, meetings, +RISC-V GitHub or shared drive files, riscv.org website or wiki pages, +etc.that include RISC-V staff, meetings, files. + +. Never discuss or use encumbered information in any RISC-V venue unless +it is clearly identifiable as greater than 20 years old (e.g. published +paper with a date published). All later parts of this document refer to +encumbered information as items being less than 20 years old. + +. Never derive or copy or refer to encumbered information. If someone +adds something to a specification that you know is encumbered, please +alert the governing committee to determine if the specification refers +to or copies encumbered information. If it does then have it removed +from the specification. + +. You may compare your results to results the originators or their +partners or customers get from an encumbered implementation to a RISC-V +implementation. + +. Please pay attention to the fact that even though an open source +implementation may exist for an item, the documents or ideas may still +be encumbered. Unless you can solely refer to the open source code, +please treat it as encumbered information. + +. The Horizontal or ISA Committee should provide best-effort review of +specifications for the use of or reference to encumbered information and +remove it before Freeze and Vote-Ready milestones (see the +https://docs.google.com/presentation/d/1nQ5uFb39KA6gvUi5SReWfIQSiRN7hp6z7ZPfctE4mKk/edit?usp=sharing[extension +lifecycle]). + +. The RISC-V Technical Program Managers will provide final review for +encumbered information as a sign-off step to the Freeze and Vote-Ready +Milestones (requirement for public review). + +. If you want to discuss encumbered information, you should do this +outside any RISC-V venue. + +. You must also abide by the +https://riscv.org/wp-content/uploads/2020/03/RISC-V-International-Regulations-03-11-2020.pdf[RISC-V +regulations and rules] (found on the riscv.org website). If anything in +this policy is contradictory to that information, the riscv.org rules +and regulations override anything in this policy. + +. If you have any questions please send a request for a meeting +regarding this policy to help@riscv.org. + +=== Transition to start using policy + +This will be the acting policy until approved (possibly with +modifications before approval). + +=== Exceptions + +None allowed. + diff --git a/src/fast_track_extension.adoc b/src/fast_track_extension.adoc new file mode 100644 index 0000000..6cd49e3 --- /dev/null +++ b/src/fast_track_extension.adoc @@ -0,0 +1,197 @@ +[[fast_track_extension]] +== Fast Track Architecture Extension + +*One line description:* ast track process for developing "small" +architecture extensions + +*Author(s):* Greg Favor + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.7 |02-03-2024 |Clarify difference between fast track and TG-developed +extensions, venue for discussions, ownership, and "relatively +uncontentious" requirement |Greg Favor + +|1.6 |01-12/2024 |Clarify escalation path through CTO |Jeff Scheel + +|1.5 |11-02-2023 |Ensure Plan Milestone occurs |Jeff Scheel + +|1.4 |07-03-2023 |Update to reflect 30-day public review |Jeff Scheel + +|1.3 |03-15-2023 |Ensure ownership verification in the process +|Greg Favor, Jeff Scheel + +|1.2 |02-10-2022 |Clarify section 4 regarding how the TSC responds to +requests to move from Fast Track to a full TG. |Stephano Cetola + +|1.1 |02-01-2022 |Clarify getting approval from AR Committee to be fast +track and notifying TSC of fast track status. |Greg Favor + +|=== + +[IMPORTANT] +*TSC Required Notification Statement:* This document contains delegated tasks from the Technical Steering +Committee (TSC). The TSC requires notification of these delegated tasks +(highlighted in red) and reserves the right to object. If no objection +is received within 14 days after notification the decision can be +considered approved. + + +=== Rationale + +The standard Task Group process is unnecessarily heavyweight, +cumbersome, and slow for developing and standardizing "small" +architecture extensions that are relatively straightforward and +uncontentious. This proposal provides an efficient and fast way to +handle such architecture-extension proposals, without creating and +conducting a new Task Group, while ensuring suitable quality control +over this process under the oversight and approval of the relevant +Horizontal or ISA Committee. + +=== Policy + +This fast track process is a means to create a relatively small +architecture extension without the overheads of creating and running a +Task Group over several quarters or more. After initial fast track +approval (see below), all other key steps in the standard process for +development and ratification of an architecture extension apply to both +fast track and Task Group-developed extensions. + +The proposed extension should be of a relatively straightforward nature +that is of value to a significant portion of the RISC-V community. It +should address a specific and clear-cut issue or need, and cleanly fit +into the existing architecture and current solid draft extensions. This +extension may (likely will) be subject to discussion, questions, and +contention that should take place and be resolved on the relevant +governing IC/HC email list. (In contrast, where substantial actual +development work and associated discussions and decision-making - +spanning months - are needed, a Task Group should be formed to pursue +these more substantial efforts. Fast track extensions should be more +contained efforts where discussion spanning over days or weeks suffice +to resolve questions and contentions.) + +A specific person (the "proposer") should champion and shepherd the +proposal through this process. This person is also the "owner" of this +proposal. + +. Fast track architecture extension specification required before +internal RISC-V membership (not public isa-dev) review begins: + +* Indicates that it is following the "Fast Track Architecture +Extension" process. + +* Explains the motivation for and goals of the proposed extension (as +well as addressing why this extension proposal meets the criterion for +use of the "fast track architecture extension" process). + +* Describes the notable use cases. + +* Provides a complete (high level and detailed) description of the +extension including any new registers and/or new bits/fields, and any +proposed instruction or CSR encodings. + +* Typically fits within 1-4 pages of text (plus any diagrams). But the +size may be larger for some specifications that, for example, include a +set of instructions with per-instruction descriptions, or a set of CSRs +with per-CSR descriptions. + +* Generally adheres to a general RISC architectural approach, e.g., keep +hardware simple; enable and let software efficiently handle complicated +and/or corner cases; address first-order needs, not third-order needs. + +* Explains the reasoning behind any notable and non-obvious trade-off +choices, where appropriate + +* Indicates the proposed extension name which must be consistent with +the "ISA Extension Naming Conventions" chapter of the Unprivileged ISA +spec and the "ISA string branding, naming, and versioning" policy. + +* Identifies the owner/drive who will drive all activity through +ratification, including specification work and acceptance criteria +checklist items. + +. Approval for Fast Track status + +* Submit the draft specification to the AR Committee with a request for +approval to be pursued as a fast track extension (versus a request for +architecture review). + +* Owning IC/HC committee approves the owner/driver of the proposal + +* Notify TSC of fast track status approval (see above) + +. Plan Milestone + +* Fast Track specifications require a Plan Milestone Review by the Tech +Chairs as defined in the Ratification Policy. + +. Starting the internal (non-public) review process + +* Announcement of the draft specification and subsequent discussions of +it will take place using the email list of the relevant Horizontal or +ISA Committee. Announcement of this specification, including a pointer +to the mailing list that will be used for discussion, should also be +made to the email list(s) of any directly relevant Task Group(s) - so as +to attract a suitable audience for review and feedback. + +* This announcement must also be sent to help@riscv.org. + +* Two suitable required reviewers of the proposed specification should +be identified (with their agreement) - to ensure a minimum level of +meaningful review. Preferably these should come from outside the +proposer’s organization. + +. During the internal review process + +* Comments and questions should be addressed as appropriate via the +email list. + +* Changes should be incorporated into a revised draft specification for +final review via the email list. + +* For smaller proposals, it is suggested that the time elapsed between +the announcement of a draft specification and a subsequent revised draft +specification should be at most four weeks, with an additional week for +the last review. Some draft specifications may warrant a longer review +period. + +* Anyone can request to the TSC at any time that this extension proposal +switch to following the "full" process for developing an extension +(i.e. becoming part of the work of an existing or new Task Group). +Generally this would be in response to it becoming clear that the +proposal does not meet the criterion for using the "Fast Track +Architecture Extension" process. The TSC will consider these requests, +vote if necessary, and respond by explaining their reasoning to either +keep the Fast Track or change to a full Task Group. ++ +To make such a request, send an email to help@riscv.org with the name of +the extensions and brief rationale for the request. The RISC-V Staff +will then work with you and the TSC to handle the request. + +. Deliverables required before public review can begin*+ +* Final draft specification of the proposed extension + +* The checklist requirements and related guidances in the standard +Definition of Done Policy apply to fast track extensions as well. In +particular, all "freeze" deliverables are required. But some of these +can be proposed to be delivered after the official freeze and/or +ratification vote - with identification of a date and the resources to +complete the work (on a time-scale of weeks to months, not quarters to a +year). The Opcode and Consistency Review requirement cannot be postponed +though. + +* Filled out Fast Track Definition of Done spreadsheet. (Make a copy of +the template found in the template directory +https://drive.google.com/drive/folders/1hzoPukaf5I-r12kdjpMY5KetoYfvHeCb?usp=sharing[here].) + +* This spreadsheet and any associated waivers must be submitted to Tech +Chairs and approved. + +. Public review + +* The proposer, the two chairs of the relevant Horizontal or ISA +Committee, and two others outside the proposer’s organization must agree +to push for public review and then present such a motion to the `tech' +email list - with a two-week period for objections to be raised. + +* Barring any "reasonable" objection, the final draft specification +enters the standard 30-day public review process. This is announced via +email to `isa-dev' and to the `tech' email list. + +. Approval by TSC + +* All comments from the public review must be addressed. + +* The proposer, the two chairs of the relevant Horizontal or ISA +Committee, and two others outside the proposer’s organization must agree +to push for approval and then present such a motion to the +`tech-announce' email list (tech-announce@lists.riscv.org) - with a +two-week period for objections to be raised. + +* Barring any reasonable objection, the final proposal is submitted to +the TSC for an approval vote once the two-week window has passed. The +final proposal must include discussion of the results of the public +review including any outstanding objections. + +* Once approved by the TSC, a top sheet is sent to the board with links +to: each of the DoD deliverables, waiver requests and explanations. The +links are to the extension-specific documents for each line item to +enable the TSC and Board members to quickly and easily look up the +specific details. + + +=== Transition to start using policy + +Immediately, once approved. + +=== Exceptions + +The CTO is the escalation path for all policy issues, with the authority +to resolve them or, if necessary, escalate further to the TSC or the +BOD. diff --git a/src/friendly_terminology.adoc b/src/friendly_terminology.adoc new file mode 100644 index 0000000..f880dcb --- /dev/null +++ b/src/friendly_terminology.adoc @@ -0,0 +1,76 @@ +[[friendly_terminology]] +== Friendly Terminology + +*Version:* 1.2 + +*One line description:* Modern word choice for terminology that is +friendly for everyone + +*Author(s):* Mark Himelstein + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|Ver |Date |Details |Email +|1.2 |2023-08-03 |Utilize Inclusive Language Initiative. Enable +extensions. |Jeff Scheel + +|1.1 |2022-1-13 |Comment acceptance and cleanup for clarity. Add version +history. |Jeff Scheel + +|1.0 |2020-11-25 |Original version |Mark Himelstein + +|=== + +=== Rationale + +Historical word choice is no longer considered acceptable so we need to +change some existing terminology in RISC-V documentation (created and +owned) as well as future documentation. + +=== Policy + +Employ inclusive and friendly terminology. + +. The RISC-V Foundation, like the Linux Foundation, will use the +Inclusive Naming Initiative (https://inclusivenaming.org/[link]) for +wordlists, actions, and recommended replacements. + +. When found, we should go back and remove terms that are not +inclusive. + +. Changes should be made as soon as reasonably possible to existing +documents. + +. Members can report language that needs to change to help@riscv.org at +any time. + +. Use the RISC-V RISC-V Help Tickets hosted in GitHub +(https://help.riscv.org) to keep track of needed changes. Set Goal dates +for completion in the issue. + +. RISC-V staff will address any necessary items in the Chairs meeting +monthly (and as appropriate to the TSC and BOD) + +. New specifications are reviewed during the Freeze and +Ratification-Ready milestone work in the Status Checklist. + +=== Exception handling + +None allowed for RISC-V specifications. + +When RISC-V members collaborate with third-party projects or reference +third-party specifications with non-friendly terminology, these +references may not be avoidable but should be used sparingly. + +Should the Inclusive Naming Initiative recommended replacements not meet +the needs of the RISC-V environment, alternatives should be raised to +the Architecture Review Committee to receive a request and make a +decision. + +Additional words and replacement terms should be documented here when +decided: + +[width="100%",cols="<20%,<30%,<50%",options="header",] +|=== +|Term(s) |Recommended Replacement |Rationale for addition +|master/slave |manager/subordinate |Existing definitions do not meet +need +|=== + +=== Transition to start using policy + +Effective immediately and strive to prevent known non-friendly +terminology. diff --git a/src/github_administration.adoc b/src/github_administration.adoc new file mode 100644 index 0000000..3221830 --- /dev/null +++ b/src/github_administration.adoc @@ -0,0 +1,190 @@ +[[github_administration]] +== GitHub Repo Structure & Administration + +*Version:* 1.2 + +*One line description:* This policy governs use of RISC-V’s GitHub +organization. + +*Author(s):* Stephano Cetola, Arun Thomas + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.2 |2024-01-12 |Change escalation path to occur through CTO |Jeff Scheel + +|1.1 |2022-01-13 |Comment acceptance and updates for clarity. Add version history. |Jeff Scheel + +|0.1 |2020-10-23 |Original draft | Stephano Cetola, Arun Thomas + +|=== + +=== Rationale + +This document will cover the use of GitHub repositories for RISC-V. The +goal is to work on specifications in a unified way and to promote +collaboration and an "upstream first" mentality for all software and +firmware development. + +=== Policy + +==== General Repo Guidelines + +* All RISC-V repositories will be created by RISC-V Staff. To request a +new repo, send an email to help@riscv.org with information about the +project such as the expected contents, i.e. meeting documents, +specification, code, etc. + +** The TPMs will create the repo with standard files such as a +README.md, a LICENSE (always on open source license per RISC-V +guidelines), and other files based on the project type. For example, the +https://github.com/riscv/docs-spec-template/[docs-spec-template] (riscv +template repo) is used for specifications and +https://github.com/riscv-admin/template-group-admin[template-group-admin] +(riscv-admin template repo) for groups. + +** The repo location may be one of several RISC-V GitHub organization +based on the content. See the +https://wiki.riscv.org/display/TECH/GitHub+Repo+Map[RISC-V TECH wiki +GitHub Repo Map page]. + +** The repo Administrators will default to Chair and Vice-chair of the +group. This enables the group’s leadership to assign additional roles as +needed for administrators and maintainers. However, leadership should +only grant special privileges to contributors who are RISC-V members. +Membership verification can be addressed through RISC-V Staff and +help@riscv.org. + +* All artifacts included in the repo are provided under the repo LICENSE +file. As such, no proprietary code is allowed in a RISC-V GitHub +organization repo. + +* We try to avoid code binary files, however if it is necessary, code +binaries must be accompanied by their source code and that code must be +licensed by an https://opensource.org/licenses[OSI approved] license. + +* Every repository should be public. Private repos require approval of a +ISA Committee (IC) or Horizontal Committee (HC). + +* The best practices for the repo README file: +** Describes what the purpose of the project is from an end user +perspective. If there are numerous use cases, give some examples. Think +about this as describing how this repo fits into the RISC-V ecosystem to +a person who does not already have a working knowledge of the project. + +** Defines acronyms on first use. + +** Links to documentation in the repo if available. + +** Provides a contact email (contact help@riscv.org if you need an alias +setup). + +** If applicable, provides brief build instructions or usage examples of +how to get something meaningful out of the repo. This might be as simple +as a script for building the PDF of a specification or a list of +requirements for building a binary. + +** For specification repos, provide insight into the current state of +the document and directions on how to obtain it. + +* Every repository must contain a LICENSE file. It should: +** Be CC-BY-4.0 License for RISCV specifications + +** Use a permissive license for software/firmware. Apache 2.0 or BSD +2-clause are preferred and an https://opensource.org/licenses[OSI +approved] license is required as specified by the RISC-V International +License page. + +** Follow the license of the upstream repository for code which has an +upstream repository (e.g. GCC, LLVM, OpenJDK, etc.) + +** Be licensed by Apache 2.0 or BSD 2-clause for example code within a +specification. + +** When possible, use https://spdx.dev/[SPDX headers]. + +* Every repository should detail the contribution process, either in a +CONTRIBUTING file or the README. This information should: +** For RISC-V specifications: State that one must be a member to +contribute and provide a pointer to the RISC-V +https://riscv.org/membership/[Membership webpage]. + +** Describe the patch submission and code review process, i.e. whether +GitHub Pull Requests, Issues, mailing lists, or any other tools or test +(lint scripts) are used and in what order. + +** Articulate whether a +https://en.wikipedia.org/wiki/Contributor_License_Agreement[Contributor +License Agreement] (CLA) or +https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin[Developer +Certification of Origin] (DCO) are required. + +** Reference coding style guidelines used by the community. +* Every repository should contain a list of the maintainers, either in +the README or a MAINTAINERS file. +** List at least two maintainers for the repository. For specifications +this is the chair and the co-chair of the task group. For +non-specification repositories there should be at least 2 maintainers +listed who have admin (push) rights to the repository. Even graduated +groups or extensions need two maintainers who have time and are +committed to respond. + +** Maintainers must make sure issues have a timely response or +delegation upon submission (preferably within a couple working days) and +continue to make progress at regular intervals in a timely fashion, +preferable within 1-2 working days. + +** This can be done in the README or in a separate file. + +==== RISC-V Administrative Repos + +* Every Task Group must store their charter in a GitHub Repository + +** If there are multiple repositories for the Task Group they can choose +the appropriate one themselves or create one specifically for the +charter, meeting minutes, and general discussions. + +** The charter can be part of a README document or simply its own +file. + +** Once there is a list (perhaps on the wiki) of all the charters, it is +the responsibility of the Task Group chair to keep their charter link up +to date. This document will be amended with a link to all the charters +once available. + +* Every Task Group, SIG, and Committee must store meeting minutes in a +GitHub repo +** Please store minutes by date + +==== RISC-V Specifications Repos + +* Each ISA specification repo must contain an errata folder. + +** The folder must contain text files which detail the errata and +include the date the errata was first documented. + +** If any errata are resolved in a future commit, do not remove the +errata. Mark it as fixed and give the SHA of the commit where the errata +was addressed. + +* Upon ratification: +** A git tag should be created whose name is the version number of the +release. + +** A GitHub release should be created with the version number of the +ratified document. It must contain the source code in tar.gz or zip +format of that release and the compiled PDF document. + +* For specifications, the only users allowed push rights to the +repository are the Chair and Co-Chair of the Task Group. + +* Issues should be tracked using GitHub’s issue tracker. + +* Code must be committed using a pull request unless the code is pushed +directly by the Chair or Co-Chair and is their own work. + +* A nightly build should be run using a GitHub action and the PDF +artifact and (tar.gz or zip) source code be made publicly available. +Nightly builds need only be run if the repo changed. + +* All commits should use the +https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin[Developer +Certification of Origin] (DCO) signoff process when commiting code (see +https://git-scm.com/docs/git-commit[git-commit -s]). + +==== Software and Firmware Repos + +* We prefer to do work in upstream repositories rather than development +forks if possible. + +* We prefer that all software developed by RISC-V International member +organizations which is meant to be open source be open as early as +possible in the development lifecycle. This reduces duplication of +efforts and allows for a more open and collaborative software +ecosystem. + +* Corporate policies will often require that work be done internally +before changes are approved for publication in open source repositories. +If this is the case, please work with the Software Horizontal Committee +(HC) to ensure that duplication of efforts is minimized or completely +avoided if possible. + +* Forking Upstream for Development (Staging Upstream Repositories) +** Early software work for spec or ecosystem enablement can be done as a +fork under RISC-V, but these forks must be approved by the Software +HC. + +** Approved forks must have a working branch for each feature / bug fix. +No work should be done on the main repository branch. + +** Approved forks must follow the development model of the upstream +repository. Generally, these upstream repos will have a CONTRIBUTING +file or documentation on how to properly upstreamed code. +*** As an example, do not squash 50 commits from different authors into +1 giant commit if that upstream repo works off small incremental +changes. + +=== Exception Handling + +The CTO is the escalation path for all policy issues, with the authority to resolve them or, if necessary, escalate further to the TSC or the BOD. + diff --git a/src/gnu_toolchain_signoff_criteria.adoc b/src/gnu_toolchain_signoff_criteria.adoc new file mode 100644 index 0000000..1a7570c --- /dev/null +++ b/src/gnu_toolchain_signoff_criteria.adoc @@ -0,0 +1,67 @@ +[[gnu_toolchain_signoff_criteria]] +== GNU Tool Chain Sign-Off Criteria + +*Version:* 1.1 + +*One line description:* Criteria for acceptance of GNU tool chain modifications + +*Author(s):* Tariq Kurd, Huawei; Jeremy Bennett, Embecosm + +*Status:* Approved by Toolchain & Runtimes SSC on 28 Jan 2021 + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) +| 1.1 |2022-01-13 |Comment acceptance. Add version history. |Jeff Scheel + +| 1.0 |2019-12-16 |Document creation |Tariq Kurd, Jeremy Bennett + +|=== + + +=== Rationale + +Various task groups commission work to add GNU tool chain support for extensions and features. This policy provides a baseline set of sign-off criteria. It also serves as a framework for other software projects requiring sign-off criteria. + +Components affected are GNU assembler (GAS), GNU linker, GNU binutils, GNU CGEN, GNU Compiler Collection (GCC), libgcc (emulation library), newlib/GlibC and the GNU debugger (GDB). Not all of these are necessarily affected. Typically only C/C++ support is considered, but for some projects, support for other languages may be appropriate. + +=== Policy + +. All contributors must have FSF copyright assignment agreements in place. All code must have been transferred to the FSF, which is achieved by adding FSF copyright declarations at the top of all source files. + +. The project should have added regression tests in the following categories where relevant. + +.. GNU assembler target specific regression tests of all new instructions, including tests expected to fail, testing boundary and median cases + +.. GNU assembler target specific regression tests of **\-march** flag extensions, both to verify that new instructions are available when the flag(s) is/are set and that they are not available when not set + +.. GNU linker target specific regression tests of any new relocations added. + +.. GNU compiler target specific tests of all new builtins, intrinsic functions and preprocessor defines. + +.. GNU compiler C/C++ target specific regression tests of **\-march** flag extensions, both to verify that new builtins/intrinsics/preprocessor defines are available when the flag(s) is/are set and that they are not available when not set + +.. GNU compiler C/C++ target specific regression tests of libgcc and newlib multilibs (these tests may belong here, or in the libraries) + +.. GDB target specific regression tests of new features, such as register display, disassembly and XML target feature transfer. + +. Provide test results, which should demonstrate no new failures or unresolved tests compared to the upstream compiler. Total new successes (passes or expected failures) should match the number added above. Results should be identical for Spike and QEMU. + +[NOTE] +This may require extending Spike and/or QEMU. Depending on the specific work, the following are typically required. + + +.. GAS regression tests + +.. GNU linker regression test results + +.. GCC C/C++ regression test result + +.. GDB regression test results + +. RISC-V architectural compliance tests (ACT) for underlying architecture should pass (i.e. we haven’t done anything to break base architectures) + +. Agreed benchmark results should be presented. The choice of benchmark will depend on the specific project. For example [Embench](https://www.embench.org/) may be appropriate for a project targeting small integer RV32 machines, but not for a project targeting large multicore RV32G machines. General projects may require multiple sets of benchmarks. + +. Upstream maintainer reviews and approves the patches. + +[NOTE] +There are different maintainers for different tools, so more than one approver may be needed. + +. The project must be signed off by the Toolchain & Runtimes SSC, who have responsibility for coordination with other projects and can defer that sign-off and responsibility to appropriate subcommittees. + + +=== Exception handling + +None + +=== Transition to start using policy + +Immediate on approval + +=== Next steps + +. Review by T&R mailing list with timeout to the next T\&R meeting (2020-01-28) + +. Review of policy with recommendation by TSC & Chairs with a two week timeout on immediately following next T\&R meeting (extendable on request by reviewers by two weeks). + +. Identify at least two specific people from TSC to review the policy before it is approved. + +. Have the TSC chair and CTO review the proposal. + +. If approved, communicate to all task/sig groups commissioning GNU tool chain work. + + diff --git a/src/groups_chairs.adoc b/src/groups_chairs.adoc new file mode 100644 index 0000000..4fe4253 --- /dev/null +++ b/src/groups_chairs.adoc @@ -0,0 +1,524 @@ +[[groups_chairs]] +== Group Chair and Vice-Chair Approvals + +*Version:* 1.15 + +*One line description:* Defines RISC-V technical working groups and +selection process. + +*Author(s):* Mark Himelstein, Stephano Cetola + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.15 |2023-11-27 |Updates for Profiles and Platforms |Mark Himelstein + +|1.14 |2023-09-18 |TSC Elections and Chair/Vice-chair requirements +clarification and early departure handle TSC Elected Member cycle +changes Clarify CTO participation when IC/HC Chair or Vice-chair are +candidates for TG/SIG leadership |Jeff Scheel + +|1.13 |2023-05-03 |Clarification of leadership selection +|Jeff Scheel, Mark Himelstein + +|1.12 |2022-12-19 |Return Call for Candidate text for Committee (HC and +IC) leadership |Jeff Scheel, Mark Himelstein + +|1.12 |2022-10-05 |Updates to reflect the new 6+ majority voting as +defined by the Technical Voting policy Increase chair limits for TG/SIGS +to 3 (and still 1 HC) Explicitly remove the Call for Candidates for +Committee (HC and IC) leadership |Jeff Scheel, Mark Himelstein + +|1.11 |2022-04-20 |Only one representative per company on the TSC. As +such, clarify the elected member text. Remove HSCs. Updated vice-chair +positions for SIGs and TGs to unlimited per 3/8/2022 TSC. +|Stephano Cetola, Jeff Scheel + +|1.10 |2022-02-18 |Add Group Hierarchy Section Add required text for any +TSC notification |Stephano Cetola + +|1.9 |2022-01-13 |Comment cleanup: clarification of notification list +for disbanded SIG or TG |Jeff Scheel + +| |2021-11-08 |For non-specification-approval votes, if a member is not +eligible at the beginning of the vote, they cannot vote. |Mark Himelstein + +| |2021-10-06 |Clarify Elected TSC members term dates. Minor grammatical +fixes. |Stephano Cetola + +|1.8 |2021-10-5 |be specific that this applies all specifications and +make it clear that TGs and the governing committee need to provide the +TSC with context in order to approve a TG clearer transition information +process if there is a dispute as to where a TG reports |Mark Himelstein + +|1.7 |2021-06-22 |Update initial vote to be consistent with re-elections +vote for HCs and ICs with a majority positive vote. Add process for +creating a new HC or IC. |Mark Himelstein + +| |2021-06-10 |Add policy for disbanding SIGs and TGs. |Mark Himelstein + +| |2021-04-21 |As per Calista, Changed votes that go to the board as +majority votes with possible dissent at both TSC and BOD. define +Majority |Mark Himelstein + +| |2021-04-05 |Clarified who picks nominees for each group Added elected +members |Mark Himelstein + +| |2021-03-03 |New organization names Dotted line committee involvement +Remove org info and point to org slides HC chair & vice chair swap +|Mark Himelstein + +|1.6 |2021-02-17 |Two week post Change of affiliation only requires +notify if the chair or vice chair are still eligible according to the +policy Chair and vice chair of TSC must approve even if a nominee is +from their company |Mark Himelstein, Stephano Cetola + +|1.4 |2021-01-25 |Email to notify unchosen candidate Document 2+2 vote +Document SIG governance tightened up language |Mark Himelstein + +|0.1 |2020-08-11 |Original draft | Mark Himelstein, Stephano Cetola + +|=== + +=== Rationale + +We need this policy because we need a well defined way to evaluate new +groups, and chair and vice-chair Nominees and resolve votes in a +reasonable period of time. + +Our intent is to continue to make sure our community members have a +voice in the direction and work products we produce. However as the +organization grows, we will ask the Committees to collect and represent +their constituents ideas and positions. Nothing should go to a vote at +TSC without adequate community input and sponsorship by a Committee. If +agreements cannot be reached, the appropriate committees should escalate +as appropriate. + +Issues that are not resolved appropriately should be raised to +help@riscv.org and the RISC-V staff will ensure we get to closure. We +know that everyone cannot be happy with every decision. + +==== Introduction + +Please see the organization chart slide deck +https://docs.google.com/presentation/d/1eEVuu6lRZd9iiDnZQSZME7Q7svtTG3pGIKHPmZ79B8E/edit?usp=sharing[here] +for a high level overview of RISC-V meetings and organization groups. + +===== Group Hierarchy +Per Article 3 of the +https://riscv.org/wp-content/uploads/2020/03/RISC-V-International-Regulations-03-11-2020.pdf[RISC-V +Regulations], the technical steering committee has "jurisdiction" over +all other technical committees, subcommittees, and technical working +groups. In practice, the TSC has delegated governance where appropriate +to the Committees, which in turn delegate as appropriate to the Special +Interest Groups, and Task Groups. + +The Technical Steering Committee requires notification of some decisions that these groups are making in order to provide appropriate oversight. The TSC reserves the right to review and adjust decisions made by any of the working groups or committees. Each policy will call out, at the top of the document, if the TSC requires notification of any process detailed in a RISC-V policy document. See the TSC Required Notification Statement below for the full text. + +[IMPORTANT] +*TSC Required Notification Statement:* +This document contains delegated tasks from the Technical Steering +Committee (TSC). The TSC requires notification of these delegated tasks +(highlighted in red) and reserves the right to review and adjust at any +time. + + +===== Types of Votes + +* 6+ majority positive vote. At least 6 members of the body must vote +and the total positive votes must exceed objections. + +* Majority vote: Majority positive out of all eligible voters. + +In general: + +* Voters must be eligible at the beginning of a vote in order to vote. + +* Any dissent must be understood before approving the majority. This may +include email discussions and/or meetings. + +=== Definitions + +_Acting Chair or Vice-chair_: The people who have been appointed by the +Governing committee to help start a group. One of their many +responsibilities is to support the Governing Committee’s Call for +Candidates to find the permanent group leaders. + +_Candidates_: People who want to be considered for a position as Chair +or Vice-chair. Generally, these people have responded to a Call for +Candidates per below. + +_Nominees_: People selected by the Horizontal Committees (HCs) or ISA +Committees (ICs) or CTO and sent to the TSC for approval as the chair or +vice chair. + +=== Policy + +This policy will refer to some of the organization structure and +extension lifecycle and milestones so we have context to understand the +groups we are creating or approving chairs and vice-chairs for. + +Click +https://docs.google.com/presentation/d/1nQ5uFb39KA6gvUi5SReWfIQSiRN7hp6z7ZPfctE4mKk/edit?usp=sharing[here] +for the extension lifecycle and milestone deck. + +==== New Group Approvals + +There are 3 phases to this process for new ICs, HCs, and TGs (all 3 +referred to as "group" in this policy): + +. Inception + +. TSC Approval + +. Plan Milestone Approval + +TGs are either developing ISA specifications, Non-ISA +specifications/documents, Architectural Overview specifications, or +hybrid specifications. All new TGs must go through this approval +process. Existing TGs may finish their specs to be ratified or request a +waiver from TSC to not instantiate under this approval process. + +Remember that groups and committees are not meetings. Meetings may, in +fact, include multiple TGs or Committees in order to minimize meeting +time and optimize results. + +If there is a dispute as to where a TG reports directly (dotted line can +be many) then the committee chairs decide. If they can’t decide it gets +escalated to the CTO for resolution. The CTO acts as Acting Chair of any +committees that are in inception mode and don’t yet have an Acting +Chair. + +The Inception phase has the following steps in order: + +* For TGs, the TSC/IC/HC must identify someone to drive the process and +for HCs and ICs the CTO identifies that person. This person will be +known as the "Acting Chair" The committee may also appoint an acting +vice chair. + +* The group may start convening under the leadership of the Acting Chair +from the time the Acting Chair is appointed to help with this process. +RISC-V staff will create a groups.io email group. The Governing +Committee or CTO will notify the tech announce email group about the +group. + +* The Acting Chair should develop a description & preliminary charter +and get it approved by the governing TSC/IC/HC or CTO. The description +consists of a couple of short paragraphs describing what the group is +for and should list possible deliverables (some can be guesses). +Preferably, the maximum time allotted for this step should be 6-weeks +with the exceptions managed by Committee Chairs. + +* During this phase, the Governing Committee should send an email with +the Call for Candidates for chair and vice-chair to the +tech-announce@lists.riscv.org alias and allow 2 weeks for responses. The +Call for Candidates should include the proposed preliminary charter and +skills/background developed in the above steps. The Governing COmmittee +Chairs may get help from the RISC-V staff. + +* Candidates must provide a written Bio and a statement of intent of +what they would want to accomplish as a chair or vice chair in their own +words. The bio and statement needs to be included in the package to the +TSC. + +* The TSC/IC/HC or CTO decides among the Candidates and picks a Nominee +for chair and a nominee for vice-chair. If an TSC/IC/HC Chair or +Vice-chair is a candidate themselves, the CTO will replace them in the +decision process. The TSC/IC/HC or CTO may move forward even if it only +has a chair Nominee and fill the vice-chair later under the rules of +filing empty positions in an existing group described below. The +committee should not move forward with a vote until there is a chair +Nominee. + +* The TSC chairs or HC or IC or CTO will take the group description, +preliminary charter & Nominees and send it as a package to TSC for +approval. + +* The TSC-vote is a 6+ majority positive vote defined above for TGs and +majority positive vote for HCs and ICs. + +* The Governing Committee chairs should notify the Candidates that were +not picked as Nominees that they were not chosen in a constructive email +thanking them for offering before announcing the new chairs. + +* SIGs +** All aspects are decided by the governing committee (TSC, IC, HC) +including the charter and chairs. This does not need to go to TSC +(unless it is governed by the TSC) or Chairs for approval. SIGs should +follow the same Nominee process as TGs except the Committee approves. + +** The Committee must notify the TSC and Chairs upon approvals or state +change (creation, charter, final charter, and Nominee approval, etc.) +and send a notice to tech-announce. + +** If a SIG evolves into a TG or HC or IC, it must go to TSC for vote as +described above. Since the same process that is used to collect +Candidates and pick Nominees, the existing chair and vice-chair can be +included in the TSC vote package without redoing the call for +candidates. + +* If a chair or vice-chair changes affiliation and is still eligible +according to the policy (e.g. chair and vice-chair not from the same +company or only the vice chair can be individual member) then the TSC, +HC or IC governing the group or the CTO if it is a committee notifies +Chairs and the TSC of the change but does not need approval. + +* The chair and vice-chair may not come from the same organization. + +* Chairs must be affiliated with (i.e. a member of the organization +through) a Premier, Strategic, or Community Organization member. The +vice-chair may be an Individual member. Exceptions for this part of the +policy need a waiver. Waivers for SIGs go through the Committee +governing the SIG and for TGs through the governing committee and the +TSC. + +* The TSC and HCs and ICs must consult with any Committees that consider +the TG as a dotted-lineTG under the committee before picking Nominees. + +* One person can only hold a chair position for three groups (SIG or TG) +and one committee (HC, IC) simultaneously and may hold unlimited +vice-chair positions (TG and SIG). Exceptions can be requested with a 6+ +majority positive vote from TSC. + +* The governing committee for Profiles or Platforms SIGs or TGs is the +TSC. Any Profiles TG must have a second vice chair with a software +skillset. + +The TSC Approval phase is the act of TSC approving or rejecting the +package described at the end of the Inception phases steps. The TSC has +2 weeks to approve or reject the package. If the TSC has actionable +issues, the TSC/IC/HC may choose to go back to the inception phase and +fix the issues and submit a revised package to the TSC. The TSC may +request email or meeting interactions with the Committee and/or nominees +in their approval process. + +Once the group package is approved, the group’s first deliverable must +be a Plan milestone. We expect them to have the Plan milestone including +a final charter (see extension lifecycle), preferably within a maximum +of 8 weeks from the TSC approval, with exceptions managed by Committee +Chairs. The TG must present the Plan milestone including the final +charter to the tech chairs meeting and can request that it be added to +the meeting schedule via help@riscv.org. After the Plan Milestone +Presentation, the chairs will conduct a no-objection vote and may also +provide contingent approval pending action item resolution. Once +presented to chairs, the Committee must send the full Plan (milestone) +information to the TSC. + +A new HC or IC must be approved by a majority positive vote and approval +by the board of directors because adding a committee also adds a voting +position on the TSC. + +==== Call for Candidates + +All HC, IC, TG and SIG Chair and Vice-chair positions in RISC-V groups +must follow this process to solicit their leadership. This process +includes the following steps: + +. The forming group with guidance from its governing and dotted-line +committee(s) defines the following: + +.. A set of requirements and/or skills for the chair and vice-chair +positions. + +.. The timeframe for the call of at least 2 weeks is determined. + +. An email containing the previous step information and the group draft +charter is sent to the RISC-V Technical Announcement mailing list +(tech-announce@lists.riscv.org), the governing committee mailing list, +the dotted-line committee mailing list (if one exists), and the newly +formed group mailing list. Candidates must submit a brief bio and a +statement of intent for the position. A template for this email may be +requested from help@riscv.org. + +. Once the call timeframe has expired, the governing committee chairs +will select the new chair and vice chair in consultation with the RISC-V +CTO. Governing HCs and ICs must consult with any Dotted-line HC/IC +Chairs and Vice-chairs before picking Nominees. + +==== Filling a Chair or Vice Chair Vacancy + +* The group or IC or HC chair or vice-chair or CTO should issue a Call +for Candidates using the process defined above. + +* Once the Nominee has been selected from candidates, the Nominee(s) for +a TG, HC, and IC Chair or Vice-chair is sent to TSC +(tsc@lists.riscv.org) for approval by the appropriate Committee (and +potentially with RISC-V staff help if needed). TSC has 2 weeks to +approve or reject the Nominee with a 6+ Majority vote for TGs and a +Majority positive vote for HCs and ICs. the TSC may ask the nominating +committee for more information. Nominee(s) for a SIG Chair or Vice-chair +is approved by the Governing Committee. + +* The same policy bullets as those discussed above in the group creation +section above apply here. + +==== Chair and Vice chair swap + +* HC/IC: +** The chair and vice-chair may swap positions in a HC or IC at their +choice if the vice chair is allowed to be a chair. The rationale is that +TSC should only approve vice-chairs who would also be appropriate as +chairs for HCs and ICs. + +** This must be approved by the CTO + +** Notice must be sent to TSC and Chairs + +* TG: +** A TG may request from their governing HC/IC that the chair and +vice-chair may swap positions if the vice chair is allowed to be a +chair. + +** The governing HC/IC must approve this to even be considered. + +** We, at times, let less senior folks be vice chairs so we grow our +next generation of leaders. In this case, the HC/IC should not approve +such a swap. + +** Notice must be sent to TSC and Chairs. + +* Any swap continues to require a re-approval if the person in either +chair or vice-chair has been in the leadership role for more than 6 +months. + +==== Yearly Cycle + +Chair and Vice-Chair terms are one year. This section describes the +selection and approval process. The cycles have been staggered so we +have continuity in the leadership at one organizational level while we +conduct the cycle for another level. + +Existing Chairs and Vice Chairs may be Candidates. + +Here is the yearly cycle cadence: + +* TG or SIG Chair and Vice-Chairs: +** Driven by HC or IC governing the Task Group, + +** Request for Candidates by Feb 1, + +** Candidates identified by Feb 15. + +** Committee sends Nominees who are not incumbents (Bio, Statement of +Intent) to the TSC by Feb 22, + +** For TGs, the TSC must do a 6+ majority positive vote of new Nominees +by March 6 with an option to request for "more time needed" up to two +weeks. Incumbent chairs and vice-chairs who remain do not require a new +vote. + +** For SIGs, the Committee will pick the chair and vice chair from the +candidates. + +** Term starts after TSC votes with time for transition on or before +April 1. + +* HC and IC Chairs and Vice Chairs +** Driven by CTO, + +** Candidates identified by May 15, CTO talks with appropriate people in +chairs, committee chairs and TSC. + +** CTO Picks Nominees and sends the new nominees to TSC by June 1. +Incumbent chairs and vice-chairs who remain do not require a new vote. + +** TSC approval by Majority vote (may have dissents) by June 15, + +** Term starts July 1. + +* TSC chair and vice-chair +** Driven by CTO, + +** Call for Candidates from TSC members sent out by approximately August +1st for a 2-week period. Candidates need to provide a short biography +and statement of intent (what they want to accomplish in the position, +and if possible how). + +** Candidates may be any voting member of the TSC, including elected +members and voting committee chairs or vice-chairs. + +** Roll call or OpaVote vote by the September TSC meeting. Whichever +Candidate gets the most votes serves for a one year period starting +October 1. + +* Elected TSC members (2 strategic, 1 community/individual) +** Driven by CTO. + +** Call for Candidates by approximately May 15th. Candidates need to +provide a short biography and statement of intent (how they will engage +their constituents, what they want to accomplish in the position, and if +possible how). + +** All Candidates are voted on by their constituent groups. + +** Vote sent out to constituent groups approximately by June 15 for a 2 +week vote. Strategic members get 2 votes each for their strategic +Candidates of choice and community/individual members get one vote of +their community/individual Candidate of choice. + +** Candidates with the most votes serve a year term starting when the +vote is complete or July 1 whichever is later. The term ends on July 1 +of the following year. + +** Candidates with the most votes for the 2023 to 2024 term will serve a +9-month period starting when the vote is complete or October 1,2023 +whichever is later. The term ends on July 1, 2024. This abbreviated term +is required only once to transition to the earlier election cycle. + +** Companies may only be represented once on the TSC. As such, if the +elected member changes affiliation, or if the elected member’s company +changes membership, the company must determine which one person will +represent them on the TSC, and a special election may be held at the +discretion of RISC-V staff. + +Q4 is left off because of the holidays likely slowing down +participation. + +==== Disbanding a SIG or TG + +* The governing body that created it, must approve disbanding it. + +* HCs and ICs can decide to disband a SIG. They must notify the chairs +meeting and the TSC of the action and provide a cause. + +* HCs and ICs can ask the TSC to disband a TG. If the request emanates +from below the HC or IC, the request must be approved of and sponsored +by the HC or IC, and the HC or IC sends the request to the TSC with a +cause. The TSC will conduct a majority positive vote to approve +disbanding the TG. + +* The HC or IC must notify the members of the group with an email and +give them a day to read it before announcing the approved changes to the +HC’s or IC’s whole constituency via email on the HC/IC’s mailing list. + +* The HC or IC may decide to restart a new group , split up the group, +or manage the group’s topic area itself as it sees fit. If the group is +being recreated, the HC or IC must follow the rules found above in this +document + +==== TSC Chair and Vice Chair Early Departure + +A number of events might lead to the natural voluntary or involuntary +early departure of an individual in their role of Chair or Vice Chair of +TSC. These cases were not included in the original Policy called +https://docs.google.com/document/u/1/d/1_0Mnd5sXn8KcyOUI4-qvCdG7ITPY6vSAIhFc5Iy-URI/edit[Groups +& Chairs]. + +===== Voluntary Early Departure Cases + +Voluntary Cases include but are not limited to: + +* The person steps down from their role of Committee Chair or Vice +Chair, which granted them the TSC voting rights that enabled them to run +for the position originally. + +* The person steps down from their Strategic or Community/Individual +position as a TSC voting member which enabled them to run for the +position originally. + +* The person steps down from their role as Chair or Vice Chair of TSC. + +* The person’s company is no longer Premier or Premier TSC which enabled +them to run for the position originally (either the company chooses not +to be Premier or Premier TSC or the person leaves the company). + +In the voluntary cases, if there is a Chair or Vice Chair remaining, +they will assume the duties of both Chair and Vice Chair until the next +election. + +If there is no other Chair or Vice Chair (e.g. they had also previously +voluntarily departed), then the action depends on the time left in the +term as to whether immediate Chair/Vice-Chair elections would be held or +wait for the next election cycle. + +* In order to mitigate really short terms, if the time left in the +current Chair/Vice-Chair’s term of office is less than or equal to 4 +months, then we would hold elections for TSC Chair and Vice Chair early +and the term will be from the completion of the election until October 1 +of the following year (resulting in an elongated term). + +* If the remaining time-in-term is greater than or equal to 4 months, +then a special election will be held for TSC Chair and/or Vice Chair +whose term ends on what would have been the end of the original position +holder’s term. This scenario would result in a shortened term. + +===== Involuntary Early Departure Cases + +Involuntary cases include, but are not limited to: + +* The person loses their elected seat (as representative of Strategic or +Community / Individual members) which enabled them to run for the +position initially + +* The person loses their committee role with TSC voting privileges, +which enabled them to run for the position originally. + +In these involuntary cases, if the person is willing and the time left +in their term of office is less than 4 months, they will be allowed to +continue in the position but without their voting rights (since their +voting rights ended and retaining them would add one more voting member +to TSC during that period). + +Involuntary cases where the time left is greater than 4 months, the +remedy is the same as for the voluntary cases. + +===== Additional Considerations + +If someone becomes disqualified for both voluntary and involuntary +reasons, the voluntary remedy takes precedence. + +If a new situation arises that is not covered by the above cases, the +TSC may take a no-objection vote to determine whether to follow the +voluntary remedy, involuntary remedy, or some other remedy. + +RISC-V Technical Program Management will update the appropriate policies +based on the result of this vote and subsequent new cases that the TSC +adjudicates. + +=== Effective Date + +Acting policy as of December 1, 2020. Officially starts upon approval. +Nominations in flight should comply with as much of the policy as +possible. + +=== Escalations + +Members should escalate to their HC or IC. HCs and ICs should try to +resolve escalations and if they cannot, they bring any escalations to +the CTO. the CTO may further escalate to TSC or the BOD. + +Members who feel their escalation is not being addressed appropriately +should send email to help@riscv.org. Members should try to work through +their HC or IC first, if possible, before sending email. + diff --git a/src/intro.adoc b/src/intro.adoc index 4e7e51a..ffb0475 100644 --- a/src/intro.adoc +++ b/src/intro.adoc @@ -1,4 +1,52 @@ -[[intro]] == Introduction -The RISC-V Policies are here... +The RISC-V technical policies are detailed in this document. Each policy is defined in a standalone chapter which are provided in alphabetical order by name. A template for new policies has been included in the Appendix. + +The project to build the document is maintained in GitHub at https://github.com/riscv-admin/policies by the RISC-V Staff. Use the project issues to propose updates, make suggestions, or raise issues. + + +=== Approved policy list + +The following policies are in the Approved state and are in use: + +* Acceptance Criteria + +* Architectural Compatibility Test + +* Architecture Review + +* Committee Chair Meeting (CCM) Guests + +* Chairs Best Practices + +* Contributor + +* Development Partner Model + +* Ecosystem Labs + +* Encumbered Information + +* Fast Track Architecture Extension + +* Friendly Terminology + +* GitHub Repo Structure & Administration + +* GNU Tool Chain Sign-Off Criteria + +* Group Chair and Vice-Chair Approvals + +* ISA & Non-ISA Specifications + +* Joint Working Groups with External Organizations + +* Platforms + +* Policy + +* Profiles + +* Questions Response + +* Ratification + +* Rationale + +* Technical Voting + + +=== Draft policy list + +Policies in this section have been been drafted but not yet approved: + +* LLVM Tool Chain Sign-Off Criteria + +* OS & Hypervisor Requirements for Specification Ratification + +* Universes + +* Versioning + + +=== Archived policy list + +Policies in this section are no longer in use by RISC-V: + +* ACT Requirements for Privileged 1.11 Specification + +* Non-ISA Definition of Done + +* SAIL Requirements for Privileged 1.11 Extensions + + diff --git a/src/isa_nonisa.adoc b/src/isa_nonisa.adoc new file mode 100644 index 0000000..0e07e53 --- /dev/null +++ b/src/isa_nonisa.adoc @@ -0,0 +1,121 @@ +[[isa_nonisa]] +== ISA & Non-ISA Specifications + +*Version:* 1.1 + +*One line description:* Differentiate governance and branding for Non-ISA +specifications and artifacts + +*Author(s):* Mark Himelstein + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.1 |2022-01-28 a| Handle this: +* ISA - one only, ISA HW + +* non-ISA - small number. SW and Systems HW + +* hybrid -– where all there is a CSR(s) then include through priv either +as fast track or next rev + +|Mark Himelstein + +|1.0 |2020-07-18 |Original version | Mark Himelstein + +|=== + +=== Rationale + +The RISC-V charter is to specify the RISC-V ISA and formal models. +However we need to host, encourage, and publish specifications and other +deliverables so that the community can more easily make their RISC-V +based products successful. Examples include OSs (Linux, Zephyr, etc.), +and Trace (Trace group, Nexus). Without this differentiation, conflicts +arose about which of the non-ISA topics were the official RISC-V choice. +While RISC-V International should enable these non-ISA topics, they +should not pick one over another. The community will self choose which +is appropriate for them. Many choices may exist for non-ISA topics. +RISC-V will host them according to member wishes. + +ISA specifications only specify instructions, state and behavior and +they are unique. Non-ISA specification may include other things like +calling conventions, debug protocol message or field types, guidance on +how to write architecture tests, etc, Non-ISA may have multiple ways or +standards to do things (e.g. E-Trace and Nexus). Some existing +specifications contain both ISA and NON-ISA specifications together. It +will be up to the documentation SIG to determine the long term strategy +of how to arrange ISA and Non-ISA specifications that depend on each +other. The approval/ratification rules are different for ISA and Non-ISA +specifications and can be found in the +https://docs.google.com/document/u/2/d/1-UlaSGqk59_myeuPMrV9gyuaIgnmFzGh5Gfy_tpViwM/edit[Ratification +Policy]. + +=== Policy + +. ISA topics can be branded with "RISC-V ISA'" as a prefix like + +*_RISC-V ISA vector extension_*. Non-ISA topics can be branded with a +"for RISC-V" suffix like *_Nexus for RISC-V_*. Documents should be +clearly labeled as a *_RISC-V ISA Specification_* or for non-ISA +specifications as a *_RISC-V Ecosystem Specification_*. + +. There shall be only one Specification for ISA specification topics. +There may be multiple competing specifications for non-ISA +specifications (e.g. nexus and e-trace or linux and zyphir). + +. A hybrid non-ISA specification that only has a small number of ISA +specificationCSRs with minor behavioral impact may be split where the +ISA portion may be done as a fast track or as part of a privilege +update. The rest can be done as non-ISA through a non-ISA TG. The TG can +work with the privilege committee to push the ISA portion to +ratification. The ISA portion shall be ratified in the same year or +earlier than the non-ISA specification. Larger ISA changes must convene +a separate TSC approved TG for those changes. + +. Groups are defined by their roles and lifetimes + +.. Task Groups + +... Spawned by a committee + +... Report to their respective committees + +... create specifications (ISA or non-ISA) + +... Exist until "Done" + +.. Committees + +... Define strategy and identify gaps + +... Identify and track new and on-going issues + +... Oversee their task groups + +... Exist indefinitely (at the pleasure of the Board) + +.. Special Interest Groups + +... Explore new areas + +... Exist as long as there is (special) interest + +... Provide the continuity for a technical area beyond the lifetime of a +task group + +... May request that they morph into a Committee + +. All draft specifications must clearly delineate between what is: + +.. Normative + +... required, or + +... Optional - left to the discretion of a higher-level (e.g. Platform) +specifications + +.. Non-normative - not required; include in specification only to +provide: + +... Background, context, clarity + +... Implementation hints + +... Usage or coding hints + +.. Groups should keep ISA and Non-ISA prose or information separate and +if possible in separate documents. Non-normative text, including +explanations or implementation hints, must be clearly delineated so that +the technical editors can readily recognize it and put it in the +standard format for the released specification.Groups may choose to +place Non-ISA prose or information in a RISC-V ISA specification in a +clearly labeled delimited e.g. ("RISC-V Ecosystem comment" in a box, +"RISC-V Ecosystem Appendix", etc.) area as appropriate to provide the +reader with the best possibility to understand the RISC-V ISA +specification. + +=== Exception handling: + +Escalate exception requests for this policy to the TSC. Please allow two +weeks for a response. Please include rationale, scope, and any resulting +impact resulting from such an exception. + +=== Transition to start using policy + +. Any new specification or revision to an existing specification must +adhere to this policy. + +. Any existing policy without a revision must modify their specification +by 2021-07-01. + +. Any non-ISA items that were already ratified will be considered +approved. + diff --git a/src/joint_working_groups.adoc b/src/joint_working_groups.adoc new file mode 100644 index 0000000..3659645 --- /dev/null +++ b/src/joint_working_groups.adoc @@ -0,0 +1,98 @@ +[[joint_working_groups]] +== Joint Working Groups with External Organizations + +*Version:* 1.0 + +*One line description:* policy and process to set up a joint working group +with other organizations + +*Author(s):* Mark Himelstein + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.0 |2021-06-19|Original version | Mark Himelstein + +|=== + +=== Rationale + +RISC-V only does work for implementation independent ISA specifications +and software ecosystem components. However, in order for members to be +successful we need to ensure that the RISC-V work interoperates with +implementation dependent components including design, DV, etc. + +This policy describes a mechanism to partner with external entities to +ensure the implementation dependent components work appropriately with +RISC-V ISA and ecosystem components. + +These meetings are not covered by the RISC-V membership agreement. They +do have open source and unencumbered constraints but there is no legal +document binding us to them. + +=== Policy + +RISC-V and other entities may create a Joint Working Group (JWG). We can +create JWGs for a number of reasons including: + +* Ensuring that implementation dependent items done by other entities +and implementation independent items done by RISC-V interoperate in a +robust fashion + +* Third parties who are not part of RISC-V are working on ecosystem +components and need to coordinate with RISC-V efforts + +* Support providing implementation examples of RISC-V specifications so +that members can use the example for their own implementations + +* Develop a plan for a technology that has implications to both RISC-V +and the other entity. + +* Any members of two groups may propose a Joint Working Group. Each +entity will select one person to approve group creation. For RISC-V, +this is the CTO. The Joint working group charter will specify who from +each entity approved starting the group. The charter should also list +entities and approvers that join after creation. + +The JWG must (no particular order): + +* Have meetings that are open for anyone to join. + +* Be an open forum where all communication and documentation are +publicly available. + +* It is up to the JWG to publicize itself wherever appropriate. For +RISC-V all JWGs must be announced on Tech announce and appear in the +organization charts and spreadsheets. + +* Ensure that machine independent work products (work not related to a +specific RISC-V vendor system implementation) must be Open Source (under +a license in compliance with the "Preferred Licenses" from the +https://wiki.riscv.org/display/TECH[RISC-V Tech Wiki]) and unencumbered. +Any software related to upstream open source projects will follow the +conventions of those upstream projects, regardless of the previous +sentence. + +* Attendees agree not to bring encumbered information to these +meetings. + +* Require that each entity must identify a responsible liaison who can +represent their entity’s interests. + +* Require that each entity identify an executive responsible for their +involvement in the JWG. + +* Allow each JWG to decide it’s own internal governance (e.g. chair, +vice-chair, voting, etc.) + +* Allow all entities to publicize their involvement with and results of +the JWG. + +* Establish and publish soft goals / objectives in a github repo (exact +location will be determined shortly) + +* Create a public agenda and take minutes for each meeting stored in a +github repo (exact location will be determined shortly) + +* Abide by Anti-trust policies for the US & other countries. + +* Be an open and welcoming group + +* Abide by the RISC-V +https://riscv.org/about/risc-v-international-community-code-of-conduct/[code +of conduct] + +* Allow the JWGs to work on both machine independent and machine +dependent components. + +=== Exception handling + +Escalations get sent to the executives to resolve. + +=== Transition to start using policy + +Effective immediately + diff --git a/src/llvm_toolchain_signoff.adoc b/src/llvm_toolchain_signoff.adoc new file mode 100644 index 0000000..bf76369 --- /dev/null +++ b/src/llvm_toolchain_signoff.adoc @@ -0,0 +1,123 @@ +[[llvm_toochain_singoff]] +== LLVM Tool Chain Sign-Off Criteria + +*Version:* 0.1 + +*One line description:* Criteria for acceptance of LLVM tool chain + +*Author(s):* Nidal Faour, Jeremy Bennett, Ed Jones + +*Status:* Draft + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|0.1 |2021-05-03 |Pre-review draft |Nidal Faour, Jeremy Bennett, Ed Jones + +|=== + +=== Rationale + +Various task groups commission work to add LLVM toolchain support for +extensions and features. This policy provides a baseline set of sign-off +criteria. It also serves as a framework for other software projects +requiring sign-off criteria. + +Components affected are Clang (driver/frontend), LLVM assembler, LLVM +linker (lld), LLVM IR, lldb, libcxx. Not all of these are necessarily +affected. Typically only C/C++ support is considered, but for some +projects, support for other languages may be appropriate. + +=== Policy + +. The project should have added regression (LLVM unit test, LLVM +internal, LLVM lit). + +. Tests in the following categories where relevant. + +.. Target-specific LLVM assembler and disassembler regression tests of +new instructions or assembler directives, including tests expected to +fail, testing boundary and median cases (llvm/test/MC/RISCV). When +appropriate testing must include tests of -march flag extensions to +verify new instructions are only available when the flag(s) is/are set +and that they are not available when not set. + +.. LLVM assembler target-specific regression tests to ensure correct +generation of any new relocations added (llvm/test/MC/RISCV). + +.. LLVM linker (lld) regression tests (lld/test/ELF) for any new +relocations supported by the LLVM linker. + +.. LLVM libcxx using LIT to run libcxx testsuits and running +benchmarks. + +.. LLVM Debugger (LLDB) test suite (LLDB unit tests, shell tests, API +tests) + +.. Clang driver/frontend tests for any changes to the command line +interface (flags, search directories, multilibs) and preprocessor +defines (tests in clang/test/Driver). + +.. Clang regression target-specific code generation tests for all new +builtins (clang/test/CodeGen/RISCV). + +.. LLVM code generation tests for any new intrinsic functions or changes +to instruction generation (llvm/test/CodeGen/RISCV). + +.. LLVM IR and code generation tests for any new RISCV-specific +optimizations (llvm/test/CodeGen/RISCV). + +. For LLVM compilers intended for use with application class processors, +the project should run the LLVM test suite, a collection of application +programs. + +. The project should have added the subset of the GCC regression test +suite suitable for use with Clang/LLM. The reason why many Clang/LLVM +ports do this is that the LLVM regression tests only test as far as IR, +there are no general execution tests (the LLVM test suite is a +collection of applications, but only runs on larger machines under +"full-fat" operating systems). + +. The project should have added GCC regression tests in the following +categories where relevant. + +.. GNU compiler target specific tests of all new code generation +patterns, builtins, intrinsic functions and preprocessor defines. + +.. GNU compiler C/C++ target specific regression tests of *-march* flag +extensions, both to verify that new builtins/intrinsics/preprocessor +defines are available when the flag(s) is/are set and that they are not +available when not set + +.. GNU compiler C/C++ target specific regression tests of libgcc and +newlib multilibs (these tests may belong here, or in the libraries) + +. Provide LLVM regression test results, GCC regression test results and +(where appropriate) LLVM test suite results, which should demonstrate no +new failures or unresolved tests compared to the upstream compiler and +with all added tests passing. Total new successes (passes or expected +failures) should match the number added above. + +. RISC-V architectural compliance tests (ACT) for underlying +architecture should pass (i.e. we haven’t done anything to break base +architectures). + +. Agreed benchmark results should be presented. The choice of benchmark +will depend on the specific project. For example +https://www.embench.org/[Embench] may be appropriate for a project +targeting small integer RV32 machines, but not for a project targeting +large multicore RV32G machines. General projects may require multiple +sets of benchmarks. + +. Any submitted patches must follow the +https://llvm.org/docs/CodingStandards.html[LLVM coding standards] . +Changes should be submitted according to the +https://llvm.org/docs/DeveloperPolicy.html[LLVM developer policy]. + +. An appropriate upstream code owner reviews and approves the patches. +Note: Anybody is allowed to review code for submission to the LLVM +project, but you should seek approval from a well-known RISC-V +contributor. If submitting a change which touches generic code, wait for +additional approval from a maintainer of that code (the LLVM developer +policy has a section on finding appropriate reviewers). For a large +change affecting other targets or many generic components, propose the +changes through an RFC to the llvm-dev mailing list and link to the +submitted patch. + +. The project must be signed off by the Toolchain & Runtimes SSC, who +have responsibility for coordination with other projects and can defer +that sign-off and responsibility to appropriate subcommittees. + +=== Exception handling + +None + +=== Transition to start using policy + +Immediate on approval + +=== Next steps + +. Review by T&R mailing list with timeout to the next T&R meeting. + +. Review of policy with recommendation by TSC & Chairs with a two week +timeout on immediately following next T&R meeting (extendable on request +by reviewers by two weeks). + +. Identify at least two specific people from TSC to review the policy +before it is approved. + +. Have the TSC chair and CTO review the proposal. + diff --git a/src/nonisa_definition_of_done.adoc b/src/nonisa_definition_of_done.adoc new file mode 100644 index 0000000..e68b040 --- /dev/null +++ b/src/nonisa_definition_of_done.adoc @@ -0,0 +1,119 @@ +[[nonisa_definition_of_done]] +== Non-ISA Definition of Done + +*Version:* 1.2 + +*One line description:* What must be completed before TSC can ratify a specification or change to a specification + +*Author(s):* Gajinder Panesar, Arun Thomas and Greg Favor + +*Status:* Archived + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.2 |2021-10-05 |elaborate on custom plans | +|1.1 |2021-09-28 |require sign off for non isa specs | +|1.0 |2021-08-16 |who approves customized portions of Non-ISA DoD | +|0.1 |2021-03-22 |Original draft |Gajinder Panesar, Arun Thomas and Greg Favor + +|=== + +=== Rationale + +There needs to be a documented, detailed, and consistent set of tasks to be completed during specification development to ensure that all non-ISA work items and changes are well documented, implementable and testable at all levels. + +=== Definitions + +See the +https://docs.google.com/presentation/d/1nQ5uFb39KA6gvUi5SReWfIQSiRN7hp6z7ZPfctE4mKk/edit?usp=sharing[extension +lifecycle deck] for milestone definitions. + +"Definition of Done" is also called DoD. + +The non-ISA DoD checklist contains both plan and status of non-ISA DoD +tasks. + +=== Policy + +. When a non-ISA TGs completes the definition of done tasks and wishes +to transition to the next phase by passing the milestone, it needs to +send the definition of done checklist to chairs along with any waivers +they received prior to the milestone. + +. The TG must provide the initial copy of the checklist with their +expectations for the tasks as soon after the Kickoff milestone as +possible. The checklist for each milestone must contain committee +sign-off exactly like ISA documents. + +. The DoD checklist contains the items required for each milestone as +described in prose below. TGs should fill in the requested and status +column as appropriate. + +. The TG shall complete all of the tasks in the "List of Tasks" +section of this document. + +.. Tasks that must be completed by a specific milestone are: Plan (P), +Freeze (F), Ratification Ready (R) and Complete (C) + +.. The TG shall assign all other tasks to one of the four milestones +that is appropriate for their specific situation + +. The TG is responsible for identifying and documenting the resources +needed to get to the next milestone + +.. The group shall use the appropriate checklist template found in the +template’s directory (links below). + +.. The document shall be revision controlled so that it can be +changed. + +. The TG shall reach out to the Tech Chairs if there are any technical +or resource issues that are interfering with their completing their +tasks. + +. The TG that owns a specification is responsible for tracking the tasks +to be completed for each milestone. This is true even if some other +group does the work. + +. The TG shall follow the format and attributes of deliverables where +described in other policies. + +. The checklist also contains sign-off requirements from the HCs, ICs, +and CTO at milestones as specified in the checklist. HSCs work through +their HCs. + +. The TG shall produce and maintain their own checklist spreadsheet +(_add location link_) + +.. the task group shall identify the work that needs to be done, provide +milestone date projections, and a monthly status of each deliverable and +identify the work they can’t do with a line in the Status Spreadsheet +(_add location link_) + +.. The checklist shall be held in the "status/Per Projects Definition +of Done checklists" folder. + +.. If a task is delayed and will hold up a milestone, the group shall +send an email to Chairs explaining the issue and provide: a mitigation +plan, a date for when a mitigation plan will be ready, or a request for +help. + +.. The checklist will be used to provide an update to the TG Chairs +Committee, TSC and the CTO monthly for the board meeting. + +==== List of tasks + +. Specification: content is complete, and approved by the task group + +. Consistency cross-check. This is to ensure any new extensions that +have reached a stable milestone can operate with the non-ISA extension +seeking ratification + +. Reference model. This will have multiple uses: +* Ensures current and future implementers of the non-ISA extension have +something that can be used to cross-check their implementation with + +* For a completely hardware non-ISA extension, provides software +developers something to verify their software against + +. Architectural Compatibility Tests. This ensures the non-ISA extension +is exercised and produces information, data and stimuli that can be used +on real hardware, e.g., an RTL implementation or for software developers +to use as reference tests + +. Proof of Concept. This is required to provide data to show the +specification of the non-ISA extension defines the features correctly so +that it is implementable. For different non-ISA extensions this data +will vary. There is no requirement for the PoC itself to be available. + +. Sign-offs: see the checklist for the sign offs needed +. Any customized DoD requirements must be published as a plan including +timeline and milestones and be approved by the governing HC or IC at the +Plan milestone (as per the +https://docs.google.com/presentation/u/2/d/1nQ5uFb39KA6gvUi5SReWfIQSiRN7hp6z7ZPfctE4mKk/edit[extension +lifecycle]) and notification provided to the TSC and Board of Directors +( who may override it as they may do for any decision). If the extension +did not go through the plan milestone (e.g. it was underway before the +plan milestone was defined) then they must publish their plan before the +Freeze milestone. + +=== Exception handling + +Any Task Group wanting an exception from any part of this policy must get written approval from the Chairs. The exception should list the explicit rows that need to be waived, the cause for needing the waiver, and when they will get done. To set expectations: it is likely Chairs will only grant waivers for items in the earlier part of the DoD and unlikely that Chairs will grant permanent waivers at all. + diff --git a/src/os_hypervisor_requirements.adoc b/src/os_hypervisor_requirements.adoc new file mode 100644 index 0000000..e3056c1 --- /dev/null +++ b/src/os_hypervisor_requirements.adoc @@ -0,0 +1,121 @@ +[[os_hypervisor_requirements]] +== OS & Hypervisor Requirements for Specification Ratification + +*Version:* 0.1 + +*One line description:* Provide a reference implementation (as a patchset) +providing basic enablement for Linux (including KVM) and +FreeRTOS/Zephyr. + +*Author(s):* Philipp Tomsich + +*Status:* Draft + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|0.1 |2021-10-15 |Converted to policy from emails |Philipp Tomsich + +|0.1 |2021-09-24 |Original draft |Philip Tomsich + +|=== + +=== Rationale + +This policy provides a reference implementation (as a patchset) +providing basic enablement for the following (see `Plan Requirements'): + +* Linux stack (for applicability & impact on general-purpose software) +(i.e.: OpenSBI, Bootloader, Kernel (incl. kvm), Program loader, C +runtime, domain-specific core libraries [e.g. OpenSSL]) + +* FreeRTOS and/or Zephyr (for applicability & impact on hard real-time +software) + +To allow experimentation and evaluation of proposed extensions, an +end-to-end test case is required: this will ensure that there are no +"blind spots" (e.g., an example would be that the overhead of +vector-context switch in the OS could easily be missed otherwise) in the +evaluation and that feedback on the applicability/integration for +established operating systems can be gathered. + +The implementation is not intended as a "full" or "optimized" +implementation, but rather as a reference implementation that +illustrates an expected/envisioned baseline implementation. + +The choice of Linux as an evaluation platform is not intended to prefer +Linux over *BSD (or any other open or closed source OS), but derives +from practical considerations: most of the RISC-V software ecosystem has +already been proven with and integrated with Linux; for this reason (and +due to the resulting familiarity of our community with it), it offers +the quickest path to an end-to-end prototype. The availability of soft +real-time (Xenomai), hypervisors (kvm), and rich list of core libraries +(e.g. OpenSSL) confirm this choice. Given that hard-realtime aspects can +neither be demonstrated nor evaluated with Linux, a real-time OS target +is also needed: the choice of FreeRTOS is based on its minimalist design +(which we consider to cause the least learning curve and smallest +possible reference case for implementers). + +=== Policy + +*Application Notes* + +Application notes for the Plan milestone, Freeze milestone, and +Approval-milestone follow. + +Note that the general requirement states that reference implementations +for both a complete Linux stack (i.e. OpenSBI, Bootloader, Kernel, C +runtime, core libraries) and FreeRTOS need to be completed: this can be +qualified through an `applicability and impact statement' that needs to +be presented (by the group developing the extension) and approved (by +the Software HC) — i.e., the group states what parts of the stack they +will modify and why only these are required. + +==== Plan requirements + +* The group responsible for an extension shall create an `applicability +& impact statement' for the extension, which details the software +ecosystem impact: +** if and how boot-flow will be impacted or on-boot configuration is +required + +** if and how context-switching will be impacted + +** if and how interrupt handling will be impacted + +** if and how virtualisation will be impacted + +** if and how program startup will be impacted + +** if and how the C runtime will be impacted + +** if and how domain-specific OS libraries (e.g. OpenSSL) will be +impacted + +** if and how real-time will be impacted + +** if and how security will be impacted + +* Based on this `applicability and impact statement', the group shall +provide an explanation of the components of the Linux software stack +that will be addressed as part of their reference software enablement. +For impact in the soft-realtime domain, a reference implementation with +Linux is sufficient; if hard-realtime software is also impacted, a +reference enablement of FreeRTOS is required either instead-of (if no +demonstrable impact on a Linux stack exists) or in-addition-to Linux. + +* The `applicability & impact statement' and the `enablement plan' has +been presented to the Software HC (mailing list and/or discussion at a +HC meeting) and received sign-off from the Software HC. + +* The Software HC shall review these planning documents considering the +impact on the software ecosystem and whether independent evaluation and +experimentation are possible with the proposed plan. + +==== Freeze requirements + +* The proposed patches for the enablement have been sent to the +communities governing the upstream projects identified in the Plan as +RFC (request-for-comment) patches, including a reference to the +documentation about to be sent to public review. + +* This submission of RFC patches must: +** follow the processes of each community (e.g., being split into +individual logical patches instead of being a big-bang patch to enable +an effective review and foster good community relations), + +** CC the submission to the software mailing list + +** include a cover letter explaining the purpose of the extension, +request a community review, and reference the frozen documentation + +==== Ratification-ready requirements + +* Feedback from the upstream communities (e.g. Linux, KVM, OpenSSL, +etc.) has been received (if not: it is the TGs responsibility to follow +up!) and any comments have been treated as public review comments (and, +consequently, been addressed) + +=== Transition to start using policy + +Immediate + diff --git a/src/platforms.adoc b/src/platforms.adoc new file mode 100644 index 0000000..faebd8b --- /dev/null +++ b/src/platforms.adoc @@ -0,0 +1,391 @@ +[[platforms]] +== Platforms + +NOTE: This policy is out-of-date but will not be updated until 2023. +It is left here for historical reasons. + +*Version:* 1.0 + +*One line description:* Rules for platforms’ specifications + +*Author(s):* Philipp Tomsich + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<15%,<15%,<40%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.0 |2021-06-14 |Approved version |Philipp Tomsich +|1.0-draft-5 |2021-06-14 |Relax/reword requirement for having separate +tables clarifying HW and SW requirements. |Philipp Tomsich + +|1.0-draft-4 |2021-06-11 |Collected changes from review by the joint +Platforms HSC and Software HC leadership teams. Relax bijective +requirement on extensions being true supersets. |Philipp Tomsich + +|1.0-draft-3 |2021-05-13 |Major rework, reflecting the following changes +Platforms Naming Compatibility Testing Explicit requirements for +software and hardware |Philipp Tomsich + +|1.0-draft-2 |2021-04-29 |Partial update with results from leadership +discussions |Philipp Tomsich + +|1.0-draft-1 |2021-03-21 |Draft version for review by the committee +leadership. |Philipp Tomsich + +|1.0 |2021-03-15 |Initial public release. |Philipp Tomsich + +|=== + +=== Rationale + +This document summarizes the policies and procedures adopted for RISC-V +Platforms. + +A RISC-V Platform specifies a common, reusable runtime environment that +operating systems and applications can target to improve portability and +reuse. A RISC-V Platform provides an interoperability assurance for +compatible software (i.e, software that fulfills all requirements of a +RISC-V Platform) when run on hardware devices that are also compatible +with the same RISC-V Platform. + +All RISC-V Platforms are developed and released by the Platforms +Horizontal Subcommittee, operating under the auspices of the Software +Horizontal Committee. + +==== Intended audience + +This policy document targets the following audiences: + +* Contributors, Members, and Leadership of the Platforms Horizontal +Subcommittee + +* RISC-V technical leadership and program management + +* Architects and Integrators of software and hardware solutions for the +RISC-V ecosystem + +==== How to read this document + +This policy interleaves Rationale and Policy. + +For easier readability, the policy elements are *highlighted in bold +type*. + +[[platforms-policy]] +=== Policy + +A solid foundation for software development and interoperability is +required to support the growth of the software ecosystem for RISC-V. +From a user perspective, binary operating systems distributions (such as +the various Linux distributions) should be easily movable between +different hardware. + +This offers benefits to software developers, who can target an +interoperable, common platform with their source code and deliver base +functionality quickly (while retaining the ability to provide optimized +and value-added functionality after probing their runtime environment). + +To achieve interoperability, common Platforms are defined that specify: + +* features and capabilities that software can expect to be provided by +its environment and + +* features and capabilities all compliant software must correctly +configure and operate. + +Both hardware and software are expected to claim compatibility towards a +given Platform: such a compatibility claim indicates interoperability +for any combination of compatible hardware and software. + +==== Scope + +The focus of the platform standards is software-centric. However, both +software and hardware will be affected by the requirements put forth in +these specifications: both soft- and hardware will need to claim +compatibility against these specifications to ensure interoperability +between soft- and hardware products. + +*The Platform governs how the software can use the platform, not the +implementation details of the underlying hardware platform*. +Consequently, a Platform shall avoid performance requirements or whether +mechanisms have to be implemented in hardware (i.e. if they can be +emulated through trap-and-emulate). + +==== Specification coverage + +*The Platforms released must cover at least the following runtime +environments:* + +* *The "OS-A Platform" specifies a Platform for rich operating systems +that target application processors*. It is expected to be augmented with +industry-specific Platform extensions for "servers", "mobile", +"edge computing", "machine-learning" and "automotive". + +* *The "M Platform" provides a Platform for bare-metal applications +and small operating systems on microcontrollers.* + +Other runtime environments can be added to by the Platforms HSC based on +the processes outlined in the section "Platform lifecycle." + +*Each Platform consists of:* + +* *A base platform* + +* *extensions specifications that specify groups of application-specific +requirements* + +*A base specification and the associated extensions are released and +versioned as a single document.* + +*Extensions must have broad applicability covering the requirements of +entire market segments or industries* (e.g., "mobile," "automotive," +"server"). Extensions that cover a niche market (or would serve as a +marketing tool to individual market participants only) do not justify +the resource expenditure for standardization and maintaining +requirements and a compatibility test suite. + +*An overlap of requirements between extensions is acceptable and is +desirable wherever it simplifies the compatibility claim for products.* +E.g., from a user perspective, it will be easier to understand if +products are compliant "__with the mobile and automotive extensions__" +(both mobile and automotive include virtualization features) rather than +“_with the virtualization, mobile and automotive extensions.”_ + +==== Naming and Versioning + +*The full name of each platform shall be constructed as follows:* + +* *It is prefixed by "RISC-V".* + +* *It is postfixed by its year and a dot-separated revision number (the +original issue does not have a revision).* + +Applying this rule, the following examples result: + +* A full release of a platform will be "RISC-V OS-A Platform 2022". + +* The third reissue/revision of the same platform will be "RISC-V OS-A +Platform 2022.3". + +*Only official Platforms released by RISC-V International can use the +"RISC-V" prefix.* + +==== Machine-readable identification and experimental versions + +*For machine-identifiable purposes, we use an URI-encoded name, where +the scheme is prefixed as `riscv-platform' for official/standardized +platforms and `x-platform' for experimental versions:* + +* *riscv-platform://http://riscv.org/platform/OS-A/2022.3[riscv.org/platform/OS-A/2022.3]* + +* *riscv-platform://riscv.org/platform/OS-A/2022.3/#server-extension* + +* *x-platform://http://semiconductor-company.example.org/embrace-and-extend/007[semiconductor-company.example.org/embrace-and-extend/007]* + +*Third parties cannot use the `riscv-platform' scheme* (just like they +cannot use `RISC-V' as part of their platform name)*. + +*Replacing the `riscv-platform' or `x-platform' in the URI with `https' +shall result in a valid URL that hosts the specification and ancillary +documentation.* + +==== Claiming Compatibility + +Products implementing a RISC-V Platform shall claim compatibility with a +Platform and any applicable extensions that the product implements. + +The rules for compatibility testing are designed to ensure a surjective +compatibility mapping, but not to enforce a bijective compatibility +between platforms and software: software targeting the base Platform +must also execute in the presence of any extensions to this Platform +(but will not support the additional features introduced by the +extension), while software targeting a specific extension may require +this extension to be present (i.e. it is not required to run on the base +Platform). + +*A Platform (i.e. hardware/runtime) product compatibility claim can only +be made if a product satisfies the following:* + +* *all requirements of the respective base Platform; and* + +* *all requirements of each extension the product claims compatibility +with.* + +*No Platform (i.e. hardware/runtime) product shall claim compatibility +with an extension if it is not compatible with the respective base +specification.* + +*A Software product claiming compatibility with a Platform (and +extensions) must satisfy:* + +* *all requirements of the Platform and of all Extensions that it claims +compatibility with.* + +*These two requirements translate to the following compatibility +relationship:* + +* *Any software that works on the base-platform, will also work in the +presence of extensions (i.e. extensions are "true" extensions for +software-compatibility).* + +* *Any software that requires an extension, may not be compatible in the +absence of the extension.* + +Any compatibility claim must identify the Platforms including their +version number. + +For the self-certification of compatibility, corresponding Platform +Compatibility Tests (PCT) shall be developed and published. Refer to the +Platform Compatibility Testing Policy for details. + +In order to declare that you are platform compatible (e.g. RISC-V OS-A +Platform 2022 compatible) and use the RISC-V Platform Compatible logo, +you must pass the compatibility tests (including the profile +compatibility tests for the profile included in the platform spec). +After passing the PCT, please follow the steps at the following RISC-V +website http://www.riscv.org/TBD[www.riscv.org/TBD]. + +==== Structure + +*Platforms consist of:* + +* *Requirements (normative), made up of one or more:* +** *Mandatory subclauses* + +** *Deprecated subclauses* (see below for the meaning of Deprecated) + +* *Rationales (informative)* + +* *Application notes (informative)* + +A requirement may be made up of multiple subclauses that are combined +either as "any of" ("or"), or "all of" ("and"). This affects +compatible soft- and hardware as follows: + +* If the software must support "__A or B__," then hardware must +provide "__A and B.__" + +* If the software must support "__A and B__," then hardware must +provide "__A or B__." + +An example of subclauses and of joining subclauses is: + +_[Requirement 1]_ + +_Compatible software for the OS-A Platform must support ALL OF the +following:_ + +* _[Requirement 1, subclause 1: DEPRECATED]_ + +_All interrupts in the system are managed by an interrupt controller +compatible with the PLIC specification._ + +* _[Requirement 1, subclause 2]_ + +_All interrupts in the system are managed by an interrupt controller +compatible with the AIA specification._ + +*Every element shall have the following annotations:* + +* *A unique number* (which is not reused, even if requirements are +removed in subsequent versions)*.* Having a unique identifier is +critical to trace requirements in Platform Compatibility tests, in +discussions on Errata, or to reference Rationals and Application notes +back to Requirements. + +* *Subclauses are numbered hierarchically within each requirement.* + +* *Rationales and application notes must reference the corresponding +requirement or subclause*. + +==== Deprecation of requirements + +Platforms address both _forward compatibility_ and _backward +compatibility:_ + +* _Forward compatibility:_ Products compliant with the current version +of a platform specification are interoperable with products compliant +with future versions of the platform specification. + +* _Backward compatibility:_ Products compliant with future versions of a +platform specification should also support earlier versions. + +_Forward compatibility_ defines requirements on how the specifications +manage required features. Removing a required feature will break +_forward compatibility_; hence specifications shall not remove features +without prior warning. + +*The following deprecation policy applies for requirements:* + +* *MANDATORY subclauses have to be retained for at least one full +release cycle of the specification.* E.g., a MANDATORY requirement from +a 2022 Platform cannot be removed from the 2024 Platform, but can be +made DEPRECATED in the 2024 Platform. + +* *DEPRECATED subclauses can be dropped from the next full release of +the specification.* Note that a DEPRECATED subclause only signals the +intent of dropping the requirement, but does not imply a commitment to +drop it based on any specific schedule (e.g., delays in the +specification of alternate mechanisms may affect the ability to drop a +requirement). + +*Dropping a requirement from the specification does not require future +products to drop the respective feature, as long as the feature is not +incompatible with any new requirements.* + +==== No non-obvious requirements + +Platforms will frequently reference third-party documents, +specifications and standards. This introduces the risk of affecting +non-obvious requirements for Platform compatibility, if those external +documents do not follow the same documentation conventions or—in +turn—use references to other documents. + +*The Platforms shall add clarifying language to avoid non-obvious +requirements resulting from third-party specifications. If necessary, +the list of mandatory requirements introduced through any document +reference must be repeated in the Platform specification.* + +=== Platforms release cycle and versioning + +*Major versions of platform specifications are published in a bi-annual +cadence for even years.* While no major revisions of the platform +specifications will be published in odd years, additional extensions can +be added in these years and amendments are made to bring the Platforms +up to date with new Profiles. + +Amendments and new extensions are published as-needed. + +=== Platforms Lifecycle + +==== Inception + +*A new platform specification or an extension can be proposed to the +Platform HSC by:* + +* *The community at large* + +* *The Software Horizontal Committee, the TSC, or the CTO* + +*Any new Platform must target a market segment where interoperability is +desired, and the industry has sufficient demand to ensure that multiple +implementations (both hardware and software) are expected.* Platform +specifications that are of fringe benefit or would serve only as a +marketing tool for implementers of specific solutions are not to be +considered. + +*Community proposals are advanced through an inquiry process within the +Platform HSC to clearly define the scope, use cases, and affected hard- +and software products.* Following this inquiry process, the Platform HSC +submits the proposal—including a schedule to release—to the Software +Horizontal Committee for resource and schedule approval. + +==== Preparatory stage + +If resources and schedules are approved, the Platform HSC drafts a +specification document. After completion, it is submitted to the +Software HC for review and approval. + +==== Publication stage + +After approval by the Software HC, it is published and enters into +immediate effect. + +=== Retirement of Platforms + +Corrections are not issued to update information that has become +outdated since publication. + +The corrections are mentioned in the Front Matter of the corrected +version. + +*In general, a correction will not be issued for a publication that is +older than three years.* + +=== Exceptions + +Implementations (both hardware and software) may decide not to be +compatible with any Platform, as long as no misleading compatibility +claim is made: + +* *Products may not claim compatibility against any of the Platforms for +which they do not fulfill all requirements and pass the Platform +Compatibility test.* + +* *Products may extend on the functionality of the platform’s +specifications and provide additional functionality, as long as they +remain compatible* (i.e., they may not implement incompatible features +unless these are disabled by default). + diff --git a/src/policy.adoc b/src/policy.adoc new file mode 100644 index 0000000..b62f9d0 --- /dev/null +++ b/src/policy.adoc @@ -0,0 +1,52 @@ +[[policy]] +== Policy + +*Version:* 1.2 + +*One line description:* How to propose, approve, and adopt policies + +*Author(s):* Mark I Himelstein + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.2 | |Updated the approval process to include discussion with chairs and +a TSC vote. |Stephano Cetola + +|1.0 |2020-07-08 |Original version | Mark I Himelstein + +|=== + +=== Rationale + +We need to create and adopt policies to govern ourselves below the +bylaws. + +=== Policy + +. Use the policy template to propose a policy. All fields should be +filled in. + +. Proposer should do a preliminary review with a small group of people +before sending it broadly. + +. Send the policy out to TSC & Chairs with a two week timeout. Reviewers +may request a 2 week extension. Reviews must include a recommendation. + +. Recommendations can be (approved, declined, request more info). + +. Identify at least two specific people from TSC to review the policy +before it is approved. + +. Have the TSC chair review the proposal. + +. If approved, use the transition plan to roll it out. Communicate to +all task/sig groups. + +. CTO has final call + +. Policies that don’t affect TSC get final approval by TG Chairs at the +weekly meeting. Policies that affect things like voting must go through +the TSC for final approval vote. + +=== Exception handling + +If you want to have an exception to the rules to create a policy +escalate to TSC. If you have an exception for a specific policy follow +its exception handling. + +=== Transition to start using policy + +Immediate + diff --git a/src/profiles.adoc b/src/profiles.adoc new file mode 100644 index 0000000..c554713 --- /dev/null +++ b/src/profiles.adoc @@ -0,0 +1,144 @@ +[[profiles]] +== Profiles + +*Version:* 3.3 + +*One line description:* Rules for profiles + +*Author(s):* Mark Himelstein + +*Status:* + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|3.3 |2021-08-23 |Update to include incompatible bucket +|Mark Himelstein + +|0.1 |2020-08-09 |Original draft |Mark Himelstein + +|=== + +=== Rationale + +We need to define Profiles and how they work. (Note that profiles were called collections for a short period of time and the name was changed to match well known industry standards). Using the year we are beginning is meant so that the profile does not sound antiquated the moment it is released and since it is on the cusp of the year it could have gone either way. + +=== Definitions + +Organization acronyms can be found in the organization slide doc +https://docs.google.com/presentation/d/1eEVuu6lRZd9iiDnZQSZME7Q7svtTG3pGIKHPmZ79B8E/edit?usp=sharing[here]. + +"RVI" means the RISC-V International + +"Architecture" means the RISC-V architectural specifications include +the privileged, unprivileged ISAs and their extensions. + +"Profiles" refers to a base ISA and one or more extensions that are +specified as a group (see profiles & platforms TS) so that applications +can be compiled once and run on different implementations and get the +same results. Similarly, for Operating Systems and Non-U-mode code. +Architecture Profiles have required, optional, and unsupported +extensions and will list all ratified extensions in one of those 3 +groups. Architecture Profiles have types and at this time there are 2 +types : application ("A"), microcontroller ("M") . TSC reserves the +right to add other letters to be defined later. We intend there to be a +very small number of types. + +"Profile String" refers to the string that specifies the Architecture +Profile, version year, and optional width. +RV[TYPE][2-DIGIT-YEAR][Optional_WIDTH]. See the definition of +Architecture Profile for the field values. + +"Application" (A) Architecture Profile refers to the extension +targeted for a rich Application environment with a multi-user, +multi-process operating system. + +"Microcontroller" (M) Architecture Profile refers to a simple +microcontroller without support of virtual memory, which are likely to +either run bare metal applications or a simple RTOS. + +"Required" extensions in a collection must be implemented to be +compliant with the Architectural Profile. + +"Optional" extensions in an Architecture Profile may optionally be +implemented in a collection but if they are present (known by discovery) +and enabled, then software for this Architecture Profile is expected to +handle the extension for purposes of context switching. Portable code +cannot rely on optional extensions being present. Two optional +extensions may be incompatible with each other and must be well +documented. + +"Unsupported" extensions in a collection may be incompatible with the +required and optional extensions or may require the implementers to +develop and maintain all mode’s software in order to use the extension. +Unsupported extensions may be, for example, extensions that are meant +for typical use in another collection type like using fast interrupts +which are targeted at the microcontroller type in the application +collection type. + +"Incompatible" extensions are not possible given the required and +optional extensions. For example Zfinx will likely be optional in RVM +but incompatible with RVA because the floating point instructions use +the separate floating point registers. + +=== Policy + +==== Profiles: + +. Profiles are defined and approved by the TSC. + +. TSC should publish the updated roadmap by April 1 of each year, using +the previous year’s December Summit as a way to get community input and +feedback. The roadmap shall be for at least 3 years into the future so +we can plan adequate runway for long lead time extensions. + +. TSC will run a quarterly detailed review with the chairs of the TGs +and TSs developing extensions. + +. While groups (TGs or TSs) can launch discussions and groundwork about +any topic or instructions, they should only formally develop +specifications that are in the roadmap and in their charter. Exceptions +should go to TSC before the group creation process begins. Groups can +ask TSC to amend their charter to include extensions beyond their +current charter. + +. Architecture Profile strings are of the form +RV[TYPE][2-DIGIT-YEAR][Optional _WIDTH]. Examples include: RVA20, RVM22, +RVA22_64, RVS24_32. If no width is specified, all ratified widths as of +that year are included. + +. A profile must contain a complete list of all ratified extensions as +of November 15 and be grouped into these buckets: required, optional, +unsupported, and incompatible. + +. Architecture Profile definitions must be completed by November 15 of +each year and become official on December 31 of that year (and the next +year is in the name). Only ratified extensions by November 15 may be +included. The last two digits of the year are used in the Collection +string. Each extension must make sure the ecosystem integration occurs +and is upstreamed before ratification. + +. The profile for 2020 (e.g. RVA20) contains the extensions ratified in +2019, the profile for 2022 (e.g. RVA22) contains the extensions ratified +in 2021. + +. Architecture Profiles may skip years. Years 2032, 2064, 2128 will be +skipped to avoid confusion with base ISA address widths. + +. If you have released a product before the profile is approved or the +definition of done items are incomplete for extensions within a profile +(like the formal model and the architectural tests), then implementers +may test with the basic I extension tests (which are complete) and say +they are RVI20 compatible. This is a release valve for a period of time +when the profile and accompanying items are not complete. Members may +upgrade to other profile compatibility when the profile and its items +are complete, and they pass the tests. + +. An implementer can be compatible with the RVI20 profile (grandfather +mechanism) and still have non-conforming extensions if those extensions +don’t conflict in any way with required or optional standard extensions. + +=== Transition to start using policy + +This will be the acting policy until approved (possibly with modifications before approval). + +Upon approval of this policy, implementations must adhere to the policy. +Existing branding must transition within 12 months unless an exception +is granted. + +All implementers and TGs must comply with the strings and versions +described in this policy immediately. + +=== Exceptions + +Profile naming and versioning exceptions must be approved by the TSC. + diff --git a/src/question_response.adoc b/src/question_response.adoc new file mode 100644 index 0000000..0c36d97 --- /dev/null +++ b/src/question_response.adoc @@ -0,0 +1,92 @@ +[[question_response]] +== Question Response + +*Version:* 1.1 + +*One line description:* Answer member questions reliably within a SLA and +identify who is responsible for ensuring questions are answered + +*Author(s):* Mark I Himelstein + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.1 |2021-5-13 | Updates |Mark Himelstein + +|1.0 |2020-08-10 |Original version |Mark Himelstein + +|=== + +=== Rationale + +This is a best practice. We need this policy because when people ask +questions to the general email lists sometimes no one responds. +Sometimes we don’t respond because we think someone else will or should +respond or we don’t have the time. The result is that without responses +specifications get delayed. + +This policy is intended to least define the goals that we want groups, +committees and their chairs and vice-chairs to achieve. There is no +intent to enforce this in any way. Obviously there will be times that it +cannot or does not happen + +=== Policy + +This policy applies to any question from technical to procedural to +resources etc. + +TSC, Chairs and each Standing Committee must provide a mechanism for +people to ask questions. That mechanism could be a person to email, a +group email list, jira, etc. as appropriate and in accordance with other +policies (like the github policy). The mechanism must be published on +github in the README. + +The chairs of those groups should at least respond to emails within +24-48 hours M-F except on holidays (i.e. business days). + +Responses can be one of three things: + +. answer and resolve the question, + +. notify the requester that the question belongs to another +group and CC that group who in turn should respond in accordance with +this policy or +. acknowledge receipt of the question and tell the +responder when they should expect an answer by the chair or someone else +(it may take time to get someone to answer because they don’t have the +time or information or need to clarify the question, etc.) at some +(hopefully identified) period in the future. + +The requester should try to pick an appropriate group and contact that +group directly and not always send email to chairs or tech. The +requester should also make it clear when they need an answer and any +appropriate background and rationale for the question (ask yourself what +the reader of the question is likely to ask when they get the question +and include it on the initial request instead of requiring iteration). + +It is up to the chair of each group to make sure they or their delegate +respond appropriately in the time specified if possible in this policy. + +The answer should be recorded in Jira or Github issues as appropriate +but may also include adding it to, for example, issues on +specifications. + +Github is the official way to track specification Jira will be the +official way to track questions and responses in cross group +interactions. + +The final resolution may be a discrete answer or that we choose as a +group to defer the question for a fixed time or indefinitely. + +If requesters don’t know where to send a question they should do so to +help@riscv.org. + +=== Exception handling + +Escalate to help@riscv.org if you don’t get a response after trying +twice. + +Transition to start using policy: + +Acting policy as of August 10, 2020. Officially starts upon approval. + +https://docs.google.com/document/d/1muwa9dkGSjnZmNxu6qH4zWZH92YVv6bHrJLRGs6185s/edit?usp=sharing[Download +Here] diff --git a/src/ratification.adoc b/src/ratification.adoc new file mode 100644 index 0000000..42e3bda --- /dev/null +++ b/src/ratification.adoc @@ -0,0 +1,289 @@ +[[ratification]] +== Ratification + +*Version:* 1.7 + +*One line description:* These are the rules governing the ratification +of RISC-V Specifications + +*Author(s):* Mark Himelstein, Stephano Cetola + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.7 |2024-01-12 |Define escalation path through CTO |Jeff Scheel + +|1.6 |2023-03-31 |Shorten Public Review to 30 days from 45 per BoD +decision Add specification roles per Tech Govern |Jeff Scheel + +|1.5 |2023-02-10 |Remove DoD references and add in acceptance criteria +|Stephano Cetola + +|1.4 |2022-04-12 |Closure after pub review that the review is closed and +a list of the proposed changes sent to the same bodies that got notified +at the freeze milestone. Update language: remove DoD and insert +Acceptance Criteria Formatting |Mark Himelstein, +Stephano Cetola, Jeff Scheel + +|1.3 |2022-01-13 |Revive some language regarding non-ISA and resolve +comments. 10-5-2021: |Mark Himelstein + +|1.2 |2021-10-05 |Add verbiage about Non-ISA documents consistent with +the Non-ISA Acceptance Criteria policy |Mark Himelstein + +| |2021-09-09 |Clarify that HC/IC Signoff, Architectural Review, and +Waiver approval may be parallel. |Mark Himelstein + +|1.1 |2021-08-20 |Removed ISA vs Non-ISA language and replaced with +specification. |Mark Himelstein + +| |2021-08-16 |what process non usa specs go through and how it is +decided |Mark Himelstein, gfavor@ventana.com + +| |2021-05-12 |add language around non-isa documents and specs +|Mark Himelstein + +| |2021-04-22 |cleanup language around sending top sheet & cover letters +for vote for TSC and BOD |Mark Himelstein + +|0.2 |2021-04-15 |As per Calista no-dissent votes changed to Majority +votes with possible dissent. Pertinent Acceptance Criteria columns sent +to BOD in advance of ratification vote |Mark Himelstein, +Stephano Cetola + +|=== + +=== Rationale + +Ratification of extensions is one of the most important charters given to RISC-V International. This document calls out specific steps necessary such that both the groups and committees developing extensions conform to a process that is publicly documented. + +We are an open and transparent community of developers. It is our goal +to produce specifications that adhere to best open source practices. + +=== Definitions + +_Initiator_: The requester of an extension or specification. + +Anyone can request that a committee consider creating a new Task Group +or Fast Track specification. + +_Governing Committee_: the committee sponsoring and governing the +specification work. + +A Governing Committee approves progression to the next milestone. If +there are issues during the life cycle, they should be addressed by the +Governing Committee. + +Sponsorship includes sponsoring Task Group creation with TSC or +proposing a Fast Track extension with the Architecture Review Committee. + +A Governing Committee may delegate day to day execution of the +development of a specification but must be the one approving and +sponsoring the steps in the life cycle. + +_Owner_: the first point of contact for the specification. The Owner is +responsible for driving the specification through the lifecycle and +ensuring all the work gets completed to ratify the specification. + +For standard (non-Fast Track) specifications, the Owner is the Chair of +the Task Group. For Fast Track specifications, the Owner is typically +the Initiator but the Governing Committee may identify an alternative +Owner. + +If the TG members and Development Partners cannot help, the Owner needs +to escalate to the Governing Committee to resolve the resource gaps. The +Governing Committee in turn may escalate to the RISC-V CTO, who may +escalate to TSC, the RISC-V CEO, or the BOD. + +Resources should generally be identified in the Plan Milestone and any +gaps identified during the presentation to the Tech Chairs. + +Governing Committees should not sponsor a Fast Track without an +identified Owner. + +_Author_: the Author is the primary writer, editor, and organizer of a +specification. + +The Owner works with the Author to help drive a specification through +the lifecycle but the Author is not directly responsible for interfacing +with the Governing Committee or TPMs, but likely will be involved in the +specification review with the Architecture Review Committee. + +=== Policy + +The ratification process starts with the lifecycle. Please see the +lifecycle +https://docs.google.com/presentation/d/1nQ5uFb39KA6gvUi5SReWfIQSiRN7hp6z7ZPfctE4mKk/edit?usp=sharing[here]. + +Each Milestone requires that tasks get done in compliance with the +https://docs.google.com/document/d/1uJFEpTTei_Mr78MWZ9bPRDgWj85Gh14PuX4u8p7q66o/edit?usp=sharing[Acceptance +Criteria] policy. + +The process involves various groups and committees and meetings in our +organization. Please see the organization slide deck +https://docs.google.com/presentation/d/1eEVuu6lRZd9iiDnZQSZME7Q7svtTG3pGIKHPmZ79B8E/edit?usp=sharing[here] +for details on those groups and venues. + +In addition, the Freeze and Ratification-Ready milestones have well +defined steps (before and after those milestones) to complete the +ratification process. + +The TSC voting members provide approval for specifications and send them +to the Board requesting ratification. See the organization slides +referred to above for details. + +We develop specifications and other documents. The governing HC or IC +committee decides whether a document is a specification or other type of +document and requires a standard or modified process. The governing HC +or IC committee notifies the TSC and the BOD at the plan milestone of +these decisions and, as in all decisions, the TSC or BOD may choose to +override a decision. The other documents are supported by RISC-V as a +convenience and the governing HC or IC must propose the approval process +they should go through. + +Non-ISA specifications and documents may specify their own timelines and +milestones as per the Non-ISA Acceptance Criteria policy. As per policy +they must publish those decisions to the TSC and BOD. As with any +decision under the technical organizations,either the TSC or Board may +investigate and/or override the Committee and Task/Special Interest +Group decisions. + +Architectural Overview specifications and documents follow the same +process as the Non-ISA equivalent. The fundamental difference between +the two becomes topical content: Architecture Overview specifications +typically provide an overview that provides readers with the knowledge +on how to use a number of specifications in concert to implement +complete solutions. As such they may refer to existing specifications, +future specifications as well as normative text to fill in pieces +missing from those specifications. + +==== Plan Milestone + +* The Plan Milestone focuses on the planning activities for the +specification including the schedule, resources and criteria which may +be met to complete the work. The content of this information is defined +by the Acceptance Criteria. Templates are provided by the RISC-V +Staff. + +* Approval of the Plan Milestone occurs from the Tech Chairs after a +presentation of the planning information. + +* The Governing Committee works with the specification Owner to set the +Public Review duration which shall be a minimum of 30 days. The duration +will be presented as a part of the Plan Milestone Review to Tech Chairs. + +==== Freeze Milestone + +* The TG will make sure the Acceptance Criteria is accurate for the +freeze milestone and notify help@riscv.org that it is ready for signoff +(at least 2 weeks before needed) to conduct an automated signoff +process. + +* RISC-V staff will create a top sheet and cover letter from the +Acceptance Criteria and verify all of the artifacts are in the right +place in Github and use the top sheet and cover letter for the vote. +Each extension’s top sheet must include individual links in each line +item to the relevant documentation for each specific deliverable. For +example, each waived line item must link to the request for that waiver, +the rationale provided by the TSC for allowing the waiver, the TG’s plan +for completing the waived deliverable post ratification, and the results +of the vote for the waiver. Likewise, each completed line item must +include a link to the actual deliverable. For example, the +proof-of-concept line item must link to a document specifying what was +required for the proof of concept for the extension, and what was done +to meet that requirement including links to the software, RTL, +simulation results, or any other work done as part of the proof of +concept. The links are required to ensure that members of the TSC and +Board can quickly and easily look up each detail as a part of their +review. + +* The TG must complete the freeze milestone Acceptance Criteria tasks +including Committee Chari sign offs before the TG sends the +specification to the governing HC/IC for approval of the freeze +milestone. + +* The HC/IC must approve a specification ready for public review. + +Note: HC/IC sign-off may be granted contingent upon Architectural Review +completion and/or Waiver approval, allowing for parallelization of +activities. + +* RISC-V staff will send the cover letter and top sheet and +specification link to the following email lists at the beginning of the +public review cycle. +** Board of directors bod@lists.riscv.org + +** Committee Chairs Meeting (CCM) ccm@lists.riscv.org + +** Task Group Chairs tech-chairs@lists.riscv.org + +* The HC/IC will send the specification link to the following email +lists at the beginning of the review period. +** Tech - tech-announce@lists.riscv.org + +** Public review email isa-dev@groups.riscv.org + +* The email must include one email address to respond to with +comments. + +* All public review comments must be resolved even if the resolution +explains why RVI will not follow the commentor’s object or suggestion. + +* Public review comments and responses will be stored in the top +sheet. + +* Member comments may be added as a Github issue or sent as email to +isa-dev as a response to the public notification email. Non-members must +send email to isa-dev as a response to the public notification email. + +* If non-member comments have substantive suggestions that would +potentially include items normally governed by the RISC-V membership +agreement the comments should not be put into github or the +specification without the commenter becoming a member or signing a +CLA. + +* Comments and responses must be saved in the github repository for the +specification in the location and format specified by the +https://docs.google.com/document/d/1TdUWp-OUIQjsWgip7bRfhZBuUC64Upf5eyfBj7fWd_Q/edit?usp=sharing[RVI +github policy]. + +* Any commenter may dispute a comment resolution by escalating to the +CTO at cto@riscv.org if they want to dispute a comment resolution. + +* Once the comments are resolved to the committee’s satisfaction +(including escalations), the HC/IC shall send email to the same email +lists as above to announce the availability of comments and resolutions. +This must be done in advance of the Ratification-ready sign-off to +provide time for the HC/IC chairs to review. (The intent is to automate +this step.) + +==== Ratification-Ready Milestone + +* The TG will make sure the Acceptance Criteria is accurate for the +ready milestone and notify help@riscv.org that it is ready for signoff +(at least 2 weeks before needed) to conduct an automated signoff +process. + +* RISC-V staff will create a top sheet and cover letter from the +Acceptance Criteria and verify all of the artifacts are in the right +place in Github and use the top sheet and cover letter for the vote. + +* The TG must complete all of the Ratification-ready Acceptance Criteria +tasks including committee sign-offs. + +* The TG sends the specification and completed Acceptance Criteria +checklist to the Governing Committee (HC or IC) for approval. + +* Once the Governing Committee approves the specification for vote, the +HC or IC sends the vote to the tsc-vote@lists.riscv.org mailing list and +CC CCM and Chairs meetings. The TSC reserves the option of using voting +software, voting via email, or virtual meeting to hold a vote. + +* The vote requires a majority of eligible voting members of the TSC at +the time of the vote and must include the TSC chair and vice chair. The +vote may have dissents. + +* Once the TSC has voted positively, the governing HC/IC Chair will +notify the Board of Directors via email and add the ratification notice +to the next board agenda. HC/IC will send the top sheet and cover letter +to the Board and have the committee chair answer any questions from the +Board. Once the Board provides notification of Ratification, the HC/IC +will notify all of the above email lists of the official ratification. + +* The TG must complete the Acceptance Criteria tasks that were waived +and remained unfinished at the time of ratification for the complete +milestone and report on progress or roadblocks to the Chairs meeting. + +* Any ratified specification shall appear in the next available set of +profiles in one of the categories. See the Profiles policy for more +information. + +* Any ratified specification shall appear in the revision of the overall +unpriv or priv specifications as appropriate. + +* Any ERRATA must be published to those same email lists and added to +the specification in accordance with the +https://docs.google.com/document/d/1zRUSx8Cx3MhQqKCGBlhfLxhdwNMW8Ajwsv12M69y3kY/edit?usp=sharing[documentation +policy]. + +* No substantive changes (i.e., new instructions or state) may be made +to a ratified specification; these can only take the form of a new +extension in a new specification. HCs may approve any non-substantive +changes (editing, formatting, clarifications, etc.) at any time in a +ratified specification. + +=== Exceptions + +Any exceptions get escalated to the CTO who may choose to resolve the +issue, or escalate to the TSC or the CEO or the BOD. + diff --git a/src/rationale.adoc b/src/rationale.adoc new file mode 100644 index 0000000..52b6538 --- /dev/null +++ b/src/rationale.adoc @@ -0,0 +1,106 @@ +[[rationale]] +== Rationale + +*Version:* 1.1 + +*One line description:* Provide answers to a common set of question before proposing a new ISA extension or modification of an existing ISA specification + +*Author(s):* Mark Himelstein + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.1 |2020-10-13 |Minor naming updates |Mark Himelstein +|1.0 |2020-07-09 |Original version |Mark Himelstein + +|=== + +=== Rationale + +We have no common way to evaluate or understand the implications for +part or all of proposed extensions or changes to existing ratified +specifications that results in a new extension. This policy would +require the requester to answer the standard questions and make it +available before the freeze milestone (see the extensions lifecycle ppt +in the supporting docs folder). Think of this as a reviewer and voter +guide to common questions we may ask for any change. The vote is +independent of this document. The document is only intended to be +informative and the answers don’t directly change the vote outcome. It +should be as objective as possible and be explicit about countering +views. + +This way RISC-V members will be informed in a common formatted +questionnaire. It will help keep the instruction set smaller and more +maintainable. It will also expose some cases about what the owner is +proposing. + +=== Policy + +Questions may be answered with "not applicable" or "unknown" as +appropriate. Please describe why it is not applicable or unknown in the +questionnaire. Also please provide your best guess of how we can find +out more about an unknown. + +. Provide the requestor(s)’ name(s). + +. Provide date of submission. + +. Provide what group does the request emanate from? (individual, +task/sig/standing-committee group, ceo, cto, TSC, BOD, etc.). + +. Provide a date (month or quarter is ok) by which you want a vote on +the proposed item. + +. Please fill this in as one of the pieces of information at The Kickoff +milestone or at the latest at the Freeze milestone. If you can’t answer +something please indicate that with a "TBD" and what is blocking you +from doing so (e.g. need to do prototyping first -- will be done by +year-month-day). If the answer is no, please indicate why. FInal updates +must be made before a request for vote by TSC. + +. List of questions are below. Please explain your answers where +appropriate (like why did you say yes): + +.. Is this a functionality gap? + +.. Is this a horizontal attribute enhancement or gap? (e.g. performance, +security, RAS)? If so provide end user benefit. + +.. Does it affect a ratified ISA specification (e.g. cause there to be a +new extension related to the original extension)? + +.. Can you do this with already ratified instructions? If so, how? + +.. Which users/markets will benefit from this and how? + +.. Will this affect base or derived or custom profiles (and other +descriptions represented by markup languages)? + +.. Will this require any software change (compliance tests, bootloader, +hypervisor, os, exception/interrupt/miss code, tool chain, apps, etc.)? +If so, list and delineate: + +... changes in the number of cycles needed for any handler entry and +exit, and changes in the number of save/restores required. + +... changes required to support an extension (e.g. context switch +needing to save/restore vector registers) vs changes needed to take +advantage of the extension (e.g. kernel using vector to implement +memcpy). + +... Are there known resources who have time to implement either or both +of the above to work? + +.. If you can, please give an estimate of the expected impact on +logic/gates (s/m/l/xl). + +.. Is it part of a base ISA string’s extensions (e.g. G includes M)? + +.. are there components of the information about the extension only +available at runtime from the specific implementation (e.g max stride +for the vector extension). + +.. what is explicitly not included in this extension or change that you +might otherwise expect? + +.. Are there any unknowns or issues? + +=== Exception handling + +All escalations go to the chair of the group, if unresolved then CTO, if +unresolved then TSC. + +=== Transition to start using policy + +Start effective August 15, 2020. + +Specifications that are close to ratification/approval may not be able +to easily comply with this policy without delays to +ratification/approval this late in the game. We request that those specs +do two things: 1) answer the policy questions as best they can in a +limited time like 1 or 2 hours and 2) identify the questions which the +TG thinks might have critical answers for the TSC when they consider +ratification/approval but they cannot answer without causing delays and +hardship along with a recommendation on how, if, and when to answer +them. Alternatively they can escalate to TSC and should include some +idea about what the TG thinks might have been useful had they had this +policy in a more convenient time period. + diff --git a/src/riscv_contributor.adoc b/src/riscv_contributor.adoc new file mode 100644 index 0000000..6ef116e --- /dev/null +++ b/src/riscv_contributor.adoc @@ -0,0 +1,49 @@ +[[riscv_contributor]] +== Contributor + +*Version:* 1.1 + +*One line description:* Who can contribute to RISC-V specifications + +*Author(s):* Mark Himelstein + +*Status:* Approved + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|1.1 |2022-01-13 |Comment acceptance and cleanup for clarity. Add version history. +|Jeff Scheel + +|1.0 |2021-04-29 |Original versio |Mark Himelstein + +|=== + +=== Rationale + +The RISC-V membership agreement covers IP topics. If contributors are +not members, then they are not bound by a technical contribution +agreement. + +=== Policy + +. Contributors to RISC-V specification text must have signed a member +agreement. + +. RISC-V staff will set the github maintainers to the chairs and vice +chairs only. Additional information can be found in the +https://docs.google.com/document/d/1TdUWp-OUIQjsWgip7bRfhZBuUC64Upf5eyfBj7fWd_Q/[GitHub +Repo Structure & Administration] policy. + +. Task Groups and Committees developing specifications should not allow +any pull requests from non-members (RISC-V staff will help likely using +the certificate of origin used by the linux kernel). + +. An audit must be done before a specification goes to public review as +to whether any pull requests got into the specification by non-members. +RISC-V staff will work to identify or develop utilities to assist in +this process + +. The CTO will sign-off that the review has been done as part of +https://docs.google.com/document/d/14ZpciYwIzmuiB92_hKfwTAttTnc3rsLbWI-CpC7MdC8/edit?usp=sharing[DoD]. + +=== Exception handling + +Not applicable + +=== Transition to start using policy + +Immediately diff --git a/src/riscv_tech_policies.adoc b/src/riscv_tech_policies.adoc index 3a50426..a2338fe 100644 --- a/src/riscv_tech_policies.adoc +++ b/src/riscv_tech_policies.adoc @@ -5,7 +5,7 @@ include::../docs-resources/global-config.adoc[] :revdate: 10/2024 :revnumber: 1.0_rc1 :revremark: This document is under development. Expect potential changes. Visit http://riscv.org/spec-state for further details. -:revinfo: +:revinfo: 1.0_rc1 :preface-title: Preamble :colophon: :appendix-caption: Appendix @@ -37,6 +37,8 @@ endif::[] :footnote: :xrefstyle: short +// Block comment for lists which are empty at this time +//// [preface] == List of figures list-of::image[hide_empty_section=true, enhanced_rendering=true] @@ -48,6 +50,7 @@ list-of::table[hide_empty_section=true, enhanced_rendering=true] [preface] == List of listings list-of::listing[hide_empty_section=true, enhanced_rendering=true] +//// [WARNING] .This document is in the link:http://riscv.org/spec-state[Development state] @@ -69,9 +72,47 @@ Copyright 2024 by RISC-V International. [preface] include::contributors.adoc[] +[preface] include::intro.adoc[] -include::approved.adoc[] + +// The following chapters should be in alphabetical order +include::acceptance_criteria.adoc[] +include::act.adoc[] +include::act_priv_spec_1_11.adoc[] +include::architecture_review.adoc[] +include::ccm_guest_policy.adoc[] +include::chairs_best_practices.adoc[] +include::riscv_contributor.adoc[] +include::dev_partner.adoc[] +include::ecosystem_labs.adoc[] +include::encumbered_info.adoc[] +include::fast_track_extension.adoc[] +include::friendly_terminology.adoc[] +include::github_administration.adoc[] +include::gnu_toolchain_signoff_criteria.adoc[] +include::groups_chairs.adoc[] +include::isa_nonisa.adoc[] +include::joint_working_groups.adoc[] +include::llvm_toolchain_signoff.adoc[] +include::nonisa_definition_of_done.adoc[] +include::os_hypervisor_requirements.adoc[] +include::platforms.adoc[] +include::policy.adoc[] +include::profiles.adoc[] +include::question_response.adoc[] +include::ratification.adoc[] +include::rationale.adoc[] +include::sail_priv_spec_1_11.adoc[] +include::technical_voting.adoc[] +include::universes.adoc[] +include::versioning.adoc[] + +[appendex] +include::template.adoc[] // The index must precede the bibliography include::index.adoc[] + +//// include::bibliography.adoc[] +//// diff --git a/src/sail_priv_spec_1_11.adoc b/src/sail_priv_spec_1_11.adoc new file mode 100644 index 0000000..b0563d3 --- /dev/null +++ b/src/sail_priv_spec_1_11.adoc @@ -0,0 +1,38 @@ +[[sail_priv_spec_1_11]] +== SAIL Requirements for Privileged 1.11 Extensions + +*Version:* 1.0 + +*One line description:* This policy provides a SAIL waiver for +Privileged extensions to be ratified in 2021. + +*Author(s):* Greg Favor + +*Status:* Archived + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) +|1.0 |2021-07-21 |Initial policy. |Greg Favor +|=== + +=== Rationale + +SAIL modeling is required for all specifications being ratified under +the governance of the Privileged ISA Committee . As SAIL modeling for +the Privileged Specification v1.11 is incomplete and does not exist for +the privileged specifications, and not enough knowledgeable SAIL +resources will be available this year to develop this in time for +ratification, this policy defers the +https://docs.google.com/document/u/2/d/1Hp9ZZSzjk6Tp2pIvh33mNCj6wAoJCEqsdENQUTSruQg/edit[Definition +of Done] tasks related to SAIL until next year when suitable resources +become available. + +=== Policy + +This policy is temporary and applies only to ratification of +Privileged Specification 1.12 and Privileged architecture-related +extensions (such as the H extension, AIA-IMSIC, Sstc, Sccofpmf, Svnapot, +Svinval, Svpbmt, Smdisc, Smstateen). + +=== Transition to start using policy + +Immediate diff --git a/src/technical_voting.adoc b/src/technical_voting.adoc index 37fa9ce..7321e9a 100644 --- a/src/technical_voting.adoc +++ b/src/technical_voting.adoc @@ -1,25 +1,25 @@ -=== Technical Voting Policy +[[technical_voting]] +== Technical Voting -Version: 1.2 + -One line description: The types of votes we use in our technical +*Version:* 1.2 + +*One line description:* The types of votes we use in our technical leadership groups. + -Author(s): Mark I Himelstein, Stephano Cetola + -Status: approved + +*Author(s):* Mark I Himelstein, Stephano Cetola + +*Status:* Approved + -==== Version History - -[width="100%",cols="<25%,<25%,<25%,<25%",options="header",] +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== -|Ver |Date |Details |Email +|Ver |Date |Details |Name(s) |1.2 |2022-10-24 |Add 6+ majority for TSC for policies and group -creation. At the TSC level. Cleaned up language. |mark@riscv.org +creation. At the TSC level. Cleaned up language. |Mark Himelstein -|1.1 |2021-11-22 |Comment review and clarification |jeff@riscv.org +|1.1 |2021-11-22 |Comment review and clarification |Jeff Scheel -|1.0 |2021-05-12 |Initial commit. |stephano@riscv.org +|1.0 |2021-05-12 |Initial commit. |Stephano Cetola |=== -==== Rationale +=== Rationale Voting at the Board of Directors level is defined by the RISC-V Regulations. Those regulations leave it to the discretion of the @@ -29,20 +29,19 @@ on how they each conduct voting. We have been implementing all or part of this policy for a while and as of May 2021 finalized the type of votes necessary for each item. -==== Policy +=== Policy For all votes, dissenting votes (objections) are allowed and must be discussed by the committee in email or in a TSC meeting before a measure is approved. -===== Technical Steering Committee (TSC) +==== Technical Steering Committee (TSC) The two forms of votes are called *Majority* and *6+ Majority*. *Majority* vote requires approval from the majority of all eligible voters. This type of vote is used for: -[arabic] . Approval to send specifications to the BOD for ratification. + . HC/IC charter and chair and vice-chair approval. + . Any major organizational restructuring, voting changes, exceptions, @@ -52,7 +51,6 @@ and any other TSC specific votes not covered by the vote types below. vote is a majority of voters who voted not including abstentions. This type of vote is used for: -[arabic] . Task group preliminary charter and chair and vice chair approval + . Policies affecting TSC (e.g. group, chair, vice chair creation/election, acceptance criteria, etc.). If there is any question @@ -60,7 +58,7 @@ about whether it should be a 6+majority or a majority vote, the item should be discussed at TSC before issuing the vote. + . Ratification waivers or blanket waivers -===== Task Group Chairs +==== Task Group Chairs The only vote is called *6+ Majority*. @@ -68,7 +66,6 @@ The only vote is called *6+ Majority*. the vote is a majority of voters who voted not including abstentions. This type of vote is used for: -[arabic] . Approving policies that do not affect the TSC directly. + . Approving waivers for the Freeze Milestone + . Other technical chairs business (e.g. approving decisions we want to @@ -79,11 +76,12 @@ https://docs.google.com/document/d/1_0Mnd5sXn8KcyOUI4-qvCdG7ITPY6vSAIhFc5Iy-URI/ and Elections Policy] for details on the exact steps for HC/IC/TG/SIG creation and elections. -==== Exception handling +=== Exception handling For any questions or comments on our voting process please contact the RISC-V CTO directly. -==== Transition to start using policy +=== Transition to start using policy Immediate + diff --git a/src/template.adoc b/src/template.adoc new file mode 100644 index 0000000..d45e9df --- /dev/null +++ b/src/template.adoc @@ -0,0 +1,45 @@ +[[template]] +== New Policy Template + +To create a new policy, perform the following steps: + +. Copy all information included in the block quote below into a new file. + +. Update the `[[newname]]` label with the same name as the base neme of the new file. + +. Add a `include::newname.adoc[]` statement to the `draft.adoc` file. + +[quote] +---- +[[newname]] +== New Policy Name + +*Version:* + +*One line description:* + +*Author(s):* + +*Status:* + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) +|0.1 |YYYY-MM-DD |Original draft |Firstname Lastname +|=== + +=== Rationale + + +=== Definitions + + +=== Related documentation + + +=== Policy + + +=== Exception handling + + +=== Transition to start using policy + + +---- diff --git a/src/universes.adoc b/src/universes.adoc new file mode 100644 index 0000000..69f0eaa --- /dev/null +++ b/src/universes.adoc @@ -0,0 +1,101 @@ +[[universes]] +== Universes + +*Version:* 0.1 + +*One line description:* An optional technical area that potentially +pervasively impacts all specifications + +*Author(s):* Mark Himelstein + +*Status:* Draft + + +*Version History:* + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|0.1 |2022-10-13 |Original draft |Mark Himelstein + +|=== + +=== Rationale + +There are optional technical areas like CHERI or GPUs that could +potentially affect all or a pervasive amount of specifications. Rather +than embedding the efforts and specifications together with the +mainstream, we define Universes to establish a boundary or partition to +keep specifications easier to understand. + +Like any RISC-V topic, the efforts will have to be driven by members for +them to be successful. + +This policy describes how to establish and maintain Universes. All +efforts will now fall under a Universe. The existing efforts will fall +under the _Base_ Universe. New Universes may inherit or adopt anything +from other existing Universes (loops not allowed). + +Just as with existing SIGs and TGs and Committees, Universes do not +define meetings. We optimize meetings and try to minimize meeting +fatigue. Meetings may include committees, SIGs and TGs from multiple +Universes at the discretion of the meeting organizers. + +=== Policy + +Establishing a Universe: + +. An existing committee must sponsor a new Universe and will be the +governing committee through the process of establishing the new +Universe + +. The governing committee must create a SIG through the normal SIG +creation process for the new Universe including notify TSC (like any +other SIG and notifying them this will be a Universe). The charter of +the SIG should be the charter for the Universe. + +. The SIG will work on Universe plan which shall include: + +.. A Universe name + +.. Final charter + +.. List of potential initial deliverables (including TGs and specs and +extensions and timeframe) based on the specs and extensions in the Base +Universe. + +.. Paradigm of when something is defined in the Base Universe that will +require work product in the new Universe. + +. A Universe plan must be approved by the governing committee and then +TSC. + +. Once approved, TSC will create a non-voting committee and the CTO will +hold elections like they do for any other committee. The governing +committee’s responsibilities end once TSC approves the Universe +committee. + +Ongoing Universe activities: + +. The Universe committee does not get a TSC vote but the chairs attend +CCM and tech governance meetings. + +. The Universe may create TGs and SIGs and must comply with the normal +processes to do so. Unless agreed to by Base Universe counterparts, all +specifications will remain independent of the Base Universe +specification. Universe specifications may depend on, inherit or refer +to other Universe specifications. + +. The Universe must maintain a roadmap and update it (or have its +subgroups update it) once per month in preparation for the BOD meeting +just like all committees and groups. + +. The Universe may call its own meetings or join in other meetings (at +the discretion of the meeting organizer). + +. Any work done by the Universe must follow the lifecycle processes +including appropriate Base Universe AR(s) approval. + +. A Universe may not drive or approve any work that belongs in another +Universe. Committee chairs are the arbiter if there is any questions. + +. A Universe may establish their own AR. They must create a policy just +like the other ARs do. + +. The TSC may disband a Universe. This may occur because of non-activity +or other reasons. + +. Any referral to Universe groups or specifications must include the +Universe as a prefix (e.g. "Cheri:"). Base Universe groups or +specifications require no prefix. Anything without a prefix is expected +to be in the Base Universe. + +=== Exception handling + +If you have problems with implementing any of this, you should send an +email to help@riscv.org. + +=== Transition to start using policy + +Cheri will be the test universe and we will not create any others until +we agree that the Cheri universe is successful and the universe paradigm +is appropriate. + diff --git a/src/versioning.adoc b/src/versioning.adoc new file mode 100644 index 0000000..ae7bdd3 --- /dev/null +++ b/src/versioning.adoc @@ -0,0 +1,68 @@ +[[versioning]] +== Versioning + +*Version:* 0.1 + +*One line description:* Rules governing how we version RISC-V +artifacts + +*Author(s):* Philipp Tomsich, Stephano Cetola, Rafael Sene + +*Status:* Draft + + +[width="100%",cols="<5%,<15%,<50%,<20%",options="header",] +|=== +|Ver |Date |Details |Name(s) + +|0.1 |2019-12-16 |Original draft +|Stephano Cetola, Philipp Tomsich, Rafael Sene + +|=== + +=== Rationale + +We use version numbers for RISC-V items like specifications, standards, +and software. It’s crucial for everyone, both inside and outside of the +RISC-V community, to understand these version numbers. + +=== Policy + +==== Versioning Standard + +* We follow "semantic versioning" 2.0.0. Details can be found at +https://semver.org/spec/v2.0.0.html[SemVer]. + +* The first official version of any item is 1.0.0. + +==== Version Structure + +We follow the X.Y.Z-STATUS: + +* X (Major version): incompatible changes or major new features. + +* Y (Minor version): fixes, compatible extensions w/ limited new +functionality. + +* Z (Patch version): minor corrections and editorial adjustments. + +STATUS: + +* Development (dev): early versions with active changes, like 1.0.0-dev, +1.0.1-dev, etc. + +* Frozen (frz): versions deemed feature-complete, like 1.0.0-frz, +1.0.1-frz, etc. + +* Main/master (ratified): The final approved version without a suffix, +such as 1.0.0. + +Additional Information: + +* If need be, non-final versions can include a build date as metadata +like +[build-date]. + +* Once a ratified version is complete, any new changes begin with a new +development version and the cycle restarts. For instance, if the last +ratified version is 1.2.3, the next cycle will start with 2.0.0-dev. + +=== Exception handling + +None. + +=== Transition to start using policy + +[TEXT or "Immediate on approval"] + +=== Next steps + +. ...