diff --git a/src/acceptance_criteria.adoc b/src/acceptance_criteria.adoc index 191d630..7bedbd6 100644 --- a/src/acceptance_criteria.adoc +++ b/src/acceptance_criteria.adoc @@ -1,12 +1,12 @@ [[acceptance_criteria]] -=== 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 +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -24,13 +24,23 @@ https://docs.google.com/spreadsheets/d/1iXUZdNH6aZ-EDxsOqhYW82Ha6L7K4uVZt0-Rw9ZR Status Checklist] |Stephano Cetola |=== -===== Milestone +=== 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 +==== Task See the https://docs.google.com/spreadsheets/d/1iXUZdNH6aZ-EDxsOqhYW82Ha6L7K4uVZt0-Rw9ZR-nY/edit?usp=sharing[ISA @@ -41,15 +51,7 @@ 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. -==== 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. - -==== Policy +=== 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 @@ -62,9 +64,9 @@ checklist] by: . Providing milestone date projections and a monthly status updates + . Identifying any delays and providing mitigation plans -===== List of Tasks +==== List of Tasks -====== Freeze +===== Freeze . *Document Complete* - the document must describe the semantics of instructions or operations and any other extension-specific visible @@ -95,7 +97,7 @@ waiver. The committee may ask for revisions in the POC. + (e.g. encumbered information, friendly terminology, anonymous contributor) currently in development. -====== Ratification Ready +===== Ratification Ready . *Resolve Freeze Waivers* - Either resolve freeze waivers or get new waivers for vote-ready updating the status of the old waivers. + @@ -123,7 +125,7 @@ RISC-V profile. + (e.g. encumbered information, friendly terminology, anonymous contributor) currently in development. -===== Waivers +==== Waivers Waivers for Freeze are approved by Tech Chairs 6+ majority vote. Waivers for ratification are approved by TSC 6+ majority vote. @@ -132,7 +134,7 @@ 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 +=== 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 diff --git a/src/act.adoc b/src/act.adoc index 261913c..5045666 100644 --- a/src/act.adoc +++ b/src/act.adoc @@ -1,5 +1,5 @@ [[act]] -=== Architectural Compatibility Test +== Architectural Compatibility Test *Version:* 1.2 + *One line description:* These are the rules that explain the rationale @@ -8,8 +8,7 @@ architectural tests, and conditions for waiving failures. + *Author(s):* Allen Baum, Ken Dockser + *Status:* Approved + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -24,7 +23,7 @@ architectural tests, and conditions for waiving failures. + |=== -==== Rationale +=== 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 @@ -47,9 +46,9 @@ 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 +=== Policy -===== Who Must Test +==== 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 @@ -67,7 +66,7 @@ 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 +==== 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 @@ -100,7 +99,7 @@ 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 +==== 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 @@ -141,14 +140,14 @@ 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* +==== 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 +==== 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 @@ -169,7 +168,7 @@ the same PR number as the waiver. Waivers are categorized into Flawed-Test,Constraint-Based, and Errata-Based types. -====== Flawed-test test-case waiver +===== 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 @@ -188,7 +187,7 @@ test-report for the most recent test-suite. + architecture. Cases that involve architectural ambiguity should be resolved by clarification in the specification. -====== Constraint-based test-case waiver +===== Constraint-based test-case waiver Constraint waivers may be granted in special cases including when: @@ -203,7 +202,7 @@ 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 test-case waiver Errata-based waivers may be granted in special cases including when: @@ -256,7 +255,7 @@ 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 +==== Test-case waiver conditions When a test-case waiver is granted, it @@ -284,7 +283,7 @@ 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 +==== 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 @@ -320,7 +319,7 @@ ACT point to a major gap in the understanding of the architecture or the design verification process. ==== -==== Exceptions +=== Exceptions Exceptions to the test requirements are handled through the waiver process and changes to the ISA as mentioned above. @@ -332,3 +331,4 @@ 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 index e947ef9..30289d4 100644 --- a/src/act_priv_spec_1_11.adoc +++ b/src/act_priv_spec_1_11.adoc @@ -1,5 +1,5 @@ [[act_priv_spec_1_11]] -=== ACT Requirements for Privileged 1.11 Specification +== ACT Requirements for Privileged 1.11 Specification *Version:* 0.2 + *One line description:* This policy describes simplified Architectural @@ -7,10 +7,9 @@ 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:* Approved + - -==== Version History +*Status:* Archived + +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -21,7 +20,7 @@ the future. + |0.1 |2021-05-03 |Original draft |Greg Favor, Arun Thomas |=== -==== Rationale +=== Rationale https://docs.google.com/document/u/2/d/1ZKSLQ5HPT3E_CqTVOQlBPs7qJ9v1mpnMDXHhtOQJFcU/edit[Architectural Compatibility Tests (ACT)] are required for Privileged Specification @@ -32,7 +31,7 @@ compatibility testing methodology based on running operating system and hypervisor software that exercises new features added in Privileged Specification 1.12. -==== Policy: +=== Policy: . In lieu of member’s running ACT suite for Privileged Specification 1.12 features which are intended to be used for compatibility, @@ -70,5 +69,5 @@ corner cases. + . This policy is temporary and applies only to Privileged Specification 1.12 ratification. -==== Transition to start using policy: + +=== Transition to start using policy: + Immediate diff --git a/src/approved.adoc b/src/approved.adoc deleted file mode 100644 index 2f7be02..0000000 --- a/src/approved.adoc +++ /dev/null @@ -1,28 +0,0 @@ -[[approved]] -== Approved Policies - -Policies in this section have been approved. - -include::acceptance_criteria.adoc[] -include::act.adoc[] -include::architecture_review.adoc[] -include::ccm_guest_policy.adoc[] -include::chairs_best_practices.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::platforms.adoc[] -include::policy.adoc[] -include::profiles.adoc[] -include::question_response.adoc[] -include::ratification.adoc[] -include::rationale.adoc[] -include::riscv_contributor.adoc[] -include::technical_voting.adoc[] diff --git a/src/architecture_review.adoc b/src/architecture_review.adoc index 6bd4a3b..47a1f7a 100644 --- a/src/architecture_review.adoc +++ b/src/architecture_review.adoc @@ -1,13 +1,12 @@ [[architecture_review]] -=== 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 - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -20,7 +19,7 @@ |=== -==== Rationale +=== Rationale We need to produce robust extensions that are consistent with the ratified RISC-V specifications and RISC-V overall strategy. @@ -28,7 +27,7 @@ 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 +=== 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 @@ -47,7 +46,7 @@ There are four pieces to this process: * Opcode assignment review + * CSR assignment review -===== Process details +==== Process details * The four ISA committee chairs and their delegates, will work together to accomplish this policy. + @@ -84,7 +83,7 @@ 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 +==== 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 @@ -99,7 +98,7 @@ and enhancements are needed. Lastly, AR is required during the Ratification-Read phase if the specification text has undergone any significant changes (i.e. past simple typo corrections, formatting corrections, and very simple clarifications). -==== Exception handling +=== Exception handling All exception requests should be forwarded to the ISA committees. It is unlikely any will be granted. @@ -107,7 +106,7 @@ 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 +=== Transition to start using policy Effective immediately. This will be the acting policy while awaiting approval (possibly with modifications before approval). Any extension diff --git a/src/archived.adoc b/src/archived.adoc deleted file mode 100644 index 8e4b440..0000000 --- a/src/archived.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[[archived]] -== Archived Policies - -Policies in this section are no longer in use by RISC-V. - -include::act_priv_spec_1_11.adoc[] -include::nonisa_definition_of_done.adoc[] -include::sail_priv_spec_1_11.adoc[] diff --git a/src/ccm_guest_policy.adoc b/src/ccm_guest_policy.adoc index 2e22b57..b45b54b 100644 --- a/src/ccm_guest_policy.adoc +++ b/src/ccm_guest_policy.adoc @@ -1,12 +1,12 @@ [[ccm_guest_policy]] -=== Committee Chair Meeting (CCM) Guests +== 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 +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== @@ -18,7 +18,7 @@ |=== -==== Rationale +=== 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 @@ -26,7 +26,7 @@ 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 +=== 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 @@ -64,12 +64,13 @@ Guests are not permitted to join the general CCM for the same reasons. + may designate a stand-in. That substitute cannot vote, but can attend the meeting and participate in discussions. -==== Exception handling +=== 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 +=== Transition to start using policy Immediate + diff --git a/src/chairs_best_practices.adoc b/src/chairs_best_practices.adoc index 05a1c24..b403821 100644 --- a/src/chairs_best_practices.adoc +++ b/src/chairs_best_practices.adoc @@ -1,13 +1,12 @@ [[chairs_best_practices]] -=== 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 - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -23,14 +22,14 @@ of inappropriate behavior. |Jeff Scheel |=== -==== Rationale +=== 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 +=== Related documentation * https://docs.google.com/presentation/d/1eEVuu6lRZd9iiDnZQSZME7Q7svtTG3pGIKHPmZ79B8E/[RISC-V Technical Organization] + @@ -50,9 +49,9 @@ of Done policy] + spreadsheet] + * https://jira.riscv.org/secure/Dashboard.jspa[RISC-V Jira Dashboard] -==== Policy +=== Policy -===== Getting started +==== Getting started * Familiarize yourself with the https://docs.google.com/presentation/d/1eEVuu6lRZd9iiDnZQSZME7Q7svtTG3pGIKHPmZ79B8E/[RISC-V @@ -111,7 +110,7 @@ milestone] for the https://docs.google.com/document/u/2/d/1Hp9ZZSzjk6Tp2pIvh33mNCj6wAoJCEqsdENQUTSruQg/edit[definition of done]. + -===== Regular group meetings +==== Regular group meetings * Do as much in email without meetings as you can ** Take items offline as appropriate + @@ -158,7 +157,7 @@ conversation back to the issue at hand. + ** Report the incident to either help@riscv.org or to the code of conduct email, conduct@riscv.org. + -===== Ongoing tasks +==== Ongoing tasks * *Manage extension/feature lifecycle. This should be the highest priority* @@ -190,7 +189,7 @@ 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 +==== 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 @@ -198,7 +197,7 @@ 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 +==== Other activities * Promote the groups’ technologies in conferences and seminars + * Recognize that there are two logical roles for each group: @@ -224,10 +223,11 @@ 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 +=== Transition to start using policy Active as of now as it is only advice -==== Exceptions +=== Exceptions Not applicable + diff --git a/src/dev_partner.adoc b/src/dev_partner.adoc index 2e1eac7..92e807b 100644 --- a/src/dev_partner.adoc +++ b/src/dev_partner.adoc @@ -1,5 +1,5 @@ [[dev_partner]] -=== Development Partner Model +== Development Partner Model *Version:* 1.1 + *One line description:* Process and policies regarding being a development @@ -8,8 +8,7 @@ public review and ratification + *Author(s):* Mark Himelstein + *Status:* Approved + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -29,7 +28,7 @@ simultaneously + |=== -==== Rationale +=== 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 @@ -47,7 +46,7 @@ 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 +=== Policy Ramp project to on board get a Development Partner productive : @@ -56,7 +55,7 @@ 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 +==== General process . The RISC-V group driving the work (IC, HC, HSC, or TG) picks a liaison to work with the Development Partner. + @@ -121,10 +120,11 @@ leverage that effort on the RISC-V side). + manager/project leader per 15 students or junior Developments maximum (so a big project may need both a liaison and some managers). -==== Exception handling +=== Exception handling Not applicable -==== Transition to start using policy +=== Transition to start using policy Immediately + diff --git a/src/draft.adoc b/src/draft.adoc deleted file mode 100644 index aa3d048..0000000 --- a/src/draft.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[[draft]] -== Draft Policies - -Policies in this section have been been drafted but not yet approved. - -include::llvm_toolchain_signoff.adoc[] -include::os_hypervisor_requirements.adoc[] -include::universes.adoc[] -include::versioning.adoc[] - diff --git a/src/ecosystem_labs.adoc b/src/ecosystem_labs.adoc index f6e1288..292b632 100644 --- a/src/ecosystem_labs.adoc +++ b/src/ecosystem_labs.adoc @@ -1,13 +1,12 @@ [[ecosystem_labs]] -=== 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 - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -29,7 +28,7 @@ requirements. Allow for self-defined capacity and SLA. |Jeff Scheel |=== -==== Rationale +=== 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 @@ -45,7 +44,7 @@ improving the hardware and software ecosystem + developers and researchers. + * Connecting RISC-V Labs with vendors to provide early hardware access -==== Policy +=== Policy RISC-V Ecosystem Labs offer one or more of the following: @@ -134,9 +133,10 @@ 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 + +=== 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 + +=== Transition to start using policy + Immediately upon approval + diff --git a/src/encumbered_info.adoc b/src/encumbered_info.adoc index 0dac2ed..faefd1f 100644 --- a/src/encumbered_info.adoc +++ b/src/encumbered_info.adoc @@ -1,5 +1,5 @@ [[encumbered_info]] -=== Encumbered Information +== Encumbered Information *Version:* 1.3 + *One line description:* When and why you can or cannot discuss or @@ -7,8 +7,7 @@ reference encumbered information + *Author(s):* Mark I Himelstein + *Status:* Approved + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -22,7 +21,7 @@ process policy item |Mark Himelstein |=== -==== Rationale +=== Rationale Create a clear and definitive set of guidelines for how and when you can and cannot discuss or reference encumbered information. Policy: @@ -72,10 +71,10 @@ 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 + +=== Transition to start using policy + This will be the acting policy until approved (possibly with modifications before approval). -==== Exceptions + +=== Exceptions + None allowed. diff --git a/src/fast_track_extension.adoc b/src/fast_track_extension.adoc index 048a81a..6cd49e3 100644 --- a/src/fast_track_extension.adoc +++ b/src/fast_track_extension.adoc @@ -1,13 +1,12 @@ [[fast_track_extension]] -=== Fast Track Architecture Extension +== Fast Track Architecture Extension *One line description:* ast track process for developing "small" architecture extensions + *Author(s):* Greg Favor + *Status:* Approved + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -40,7 +39,7 @@ Committee (TSC). The TSC requires notification of these delegated tasks is received within 14 days after notification the decision can be considered approved. + -==== Rationale +=== Rationale The standard Task Group process is unnecessarily heavyweight, cumbersome, and slow for developing and standardizing "small" @@ -51,7 +50,7 @@ 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 +=== Policy This fast track process is a means to create a relatively small architecture extension without the overheads of creating and running a @@ -187,11 +186,11 @@ 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 +=== Transition to start using policy Immediately, once approved. -==== Exceptions +=== 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 diff --git a/src/friendly_terminology.adoc b/src/friendly_terminology.adoc index 9af395b..f880dcb 100644 --- a/src/friendly_terminology.adoc +++ b/src/friendly_terminology.adoc @@ -1,5 +1,5 @@ [[friendly_terminology]] -=== Friendly Terminology +== Friendly Terminology *Version:* 1.2 + *One line description:* Modern word choice for terminology that is @@ -7,8 +7,7 @@ friendly for everyone + *Author(s):* Mark Himelstein + *Status:* Approved + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -24,13 +23,13 @@ history. |Jeff Scheel |=== -==== Rationale +=== 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 + +=== Policy + Employ inclusive and friendly terminology. . The RISC-V Foundation, like the Linux Foundation, will use the @@ -50,7 +49,7 @@ 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 + +=== Exception handling + None allowed for RISC-V specifications. When RISC-V members collaborate with third-party projects or reference @@ -72,6 +71,6 @@ decided: need |=== -==== Transition to start using policy + +=== 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 index 6f1c64a..3221830 100644 --- a/src/github_administration.adoc +++ b/src/github_administration.adoc @@ -1,5 +1,5 @@ [[github_administration]] -=== GitHub Repo Structure & Administration +== GitHub Repo Structure & Administration *Version:* 1.2 + *One line description:* This policy governs use of RISC-V’s GitHub @@ -7,8 +7,7 @@ organization. + *Author(s):* Stephano Cetola, Arun Thomas + *Status:* Approved + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -21,16 +20,16 @@ organization. + |=== -==== Rationale +=== 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 +=== Policy -===== General Repo Guidelines +==== 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 @@ -115,7 +114,7 @@ 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 +==== 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 @@ -131,7 +130,7 @@ once available. + GitHub repo ** Please store minutes by date -===== RISC-V Specifications Repos +==== RISC-V Specifications Repos * Each ISA specification repo must contain an errata folder. + ** The folder must contain text files which detail the errata and @@ -158,7 +157,7 @@ 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 +==== Software and Firmware Repos * We prefer to do work in upstream repositories rather than development forks if possible. + @@ -185,7 +184,7 @@ file or documentation on how to properly upstreamed code. 1 giant commit if that upstream repo works off small incremental changes. -==== Exception Handling +=== 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 index 0ce28f5..1a7570c 100644 --- a/src/gnu_toolchain_signoff_criteria.adoc +++ b/src/gnu_toolchain_signoff_criteria.adoc @@ -1,13 +1,12 @@ [[gnu_toolchain_signoff_criteria]] -=== GNU Tool Chain Sign-Off 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 - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -18,13 +17,13 @@ |=== -==== Rationale +=== 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 +=== 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. + @@ -50,15 +49,15 @@ This may require extending Spike and/or QEMU. Depending on the specific work, t 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 +=== Exception handling None -==== Transition to start using policy +=== Transition to start using policy Immediate on approval -==== Next steps +=== 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). + diff --git a/src/groups_chairs.adoc b/src/groups_chairs.adoc index a66adc6..4fe4253 100644 --- a/src/groups_chairs.adoc +++ b/src/groups_chairs.adoc @@ -1,5 +1,5 @@ [[groups_chairs]] -=== Group Chair and Vice-Chair Approvals +== Group Chair and Vice-Chair Approvals *Version:* 1.15 + *One line description:* Defines RISC-V technical working groups and @@ -7,8 +7,7 @@ selection process. + *Author(s):* Mark Himelstein, Stephano Cetola + *Status:* Approved + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -82,7 +81,7 @@ Document SIG governance tightened up language |Mark Himelstein |=== -==== Rationale +=== 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 @@ -100,13 +99,13 @@ 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 +==== 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 +===== 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 @@ -124,7 +123,7 @@ 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 +===== Types of Votes * 6+ majority positive vote. At least 6 members of the body must vote and the total positive votes must exceed objections. + @@ -136,7 +135,7 @@ In general: * Any dissent must be understood before approving the majority. This may include email discussions and/or meetings. -==== Definitions +=== 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 @@ -151,7 +150,7 @@ _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 +=== Policy This policy will refer to some of the organization structure and extension lifecycle and milestones so we have context to understand the @@ -161,7 +160,7 @@ Click https://docs.google.com/presentation/d/1nQ5uFb39KA6gvUi5SReWfIQSiRN7hp6z7ZPfctE4mKk/edit?usp=sharing[here] for the extension lifecycle and milestone deck. -===== New Group Approvals + +==== 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): @@ -287,7 +286,7 @@ 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 +==== 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 @@ -310,7 +309,7 @@ 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 +==== 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. + @@ -325,7 +324,7 @@ 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 +==== Chair and Vice chair swap * HC/IC: ** The chair and vice-chair may swap positions in a HC or IC at their @@ -347,7 +346,7 @@ such a swap. + chair or vice-chair has been in the leadership role for more than 6 months. -===== Yearly Cycle +==== 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 @@ -418,7 +417,7 @@ discretion of RISC-V staff. Q4 is left off because of the holidays likely slowing down participation. -===== Disbanding a SIG or TG +==== 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 @@ -436,7 +435,7 @@ 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 +==== 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 @@ -444,7 +443,7 @@ 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 Early Departure Cases + Voluntary Cases include but are not limited to: * The person steps down from their role of Committee Chair or Vice @@ -477,7 +476,7 @@ 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 Early Departure Cases + Involuntary cases include, but are not limited to: * The person loses their elected seat (as representative of Strategic or @@ -495,7 +494,7 @@ 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 + +===== Additional Considerations + If someone becomes disqualified for both voluntary and involuntary reasons, the voluntary remedy takes precedence. @@ -507,13 +506,13 @@ 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 +=== 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 +=== 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 @@ -522,3 +521,4 @@ 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 index f74c5b0..0e07e53 100644 --- a/src/isa_nonisa.adoc +++ b/src/isa_nonisa.adoc @@ -1,5 +1,5 @@ [[isa_nonisa]] -=== ISA & Non-ISA Specifications +== ISA & Non-ISA Specifications *Version:* 1.1 + *One line description:* Differentiate governance and branding for Non-ISA @@ -7,8 +7,7 @@ specifications and artifacts + *Author(s):* Mark Himelstein + *Status:* Approved + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -24,7 +23,7 @@ as fast track or next rev + |=== -==== Rationale +=== 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 @@ -50,7 +49,7 @@ specifications and can be found in the https://docs.google.com/document/u/2/d/1-UlaSGqk59_myeuPMrV9gyuaIgnmFzGh5Gfy_tpViwM/edit[Ratification Policy]. -==== 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 @@ -106,12 +105,12 @@ clearly labeled delimited e.g. ("RISC-V Ecosystem comment" in a box, reader with the best possibility to understand the RISC-V ISA specification. -==== Exception handling: + +=== 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 +=== Transition to start using policy . Any new specification or revision to an existing specification must adhere to this policy. + diff --git a/src/joint_working_groups.adoc b/src/joint_working_groups.adoc index d80f89e..3659645 100644 --- a/src/joint_working_groups.adoc +++ b/src/joint_working_groups.adoc @@ -1,5 +1,5 @@ [[joint_working_groups]] -=== Joint Working Groups with External Organizations +== Joint Working Groups with External Organizations *Version:* 1.0 + *One line description:* policy and process to set up a joint working group @@ -7,8 +7,7 @@ with other organizations + *Author(s):* Mark Himelstein + *Status:* Approved + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -17,7 +16,7 @@ with other organizations + |=== -==== Rationale +=== Rationale RISC-V only does work for implementation independent ISA specifications and software ecosystem components. However, in order for members to be @@ -32,7 +31,7 @@ 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 +=== Policy RISC-V and other entities may create a Joint Working Group (JWG). We can create JWGs for a number of reasons including: @@ -89,11 +88,11 @@ of conduct] + * Allow the JWGs to work on both machine independent and machine dependent components. -==== Exception handling +=== Exception handling Escalations get sent to the executives to resolve. -==== Transition to start using policy +=== Transition to start using policy Effective immediately diff --git a/src/llvm_toolchain_signoff.adoc b/src/llvm_toolchain_signoff.adoc index 4823791..bf76369 100644 --- a/src/llvm_toolchain_signoff.adoc +++ b/src/llvm_toolchain_signoff.adoc @@ -1,13 +1,12 @@ [[llvm_toochain_singoff]] -=== LLVM Tool Chain Sign-Off Criteria +== 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 - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -16,7 +15,7 @@ |=== -==== Rationale +=== Rationale Various task groups commission work to add LLVM toolchain support for extensions and features. This policy provides a baseline set of sign-off @@ -28,7 +27,7 @@ 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 +=== Policy . The project should have added regression (LLVM unit test, LLVM internal, LLVM lit). + @@ -106,13 +105,13 @@ submitted patch. + have responsibility for coordination with other projects and can defer that sign-off and responsibility to appropriate subcommittees. -==== Exception handling + +=== Exception handling + None -==== Transition to start using policy + +=== Transition to start using policy + Immediate on approval -==== Next steps +=== 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 diff --git a/src/nonisa_definition_of_done.adoc b/src/nonisa_definition_of_done.adoc index b8eac3b..e68b040 100644 --- a/src/nonisa_definition_of_done.adoc +++ b/src/nonisa_definition_of_done.adoc @@ -1,13 +1,12 @@ [[nonisa_definition_of_done]] -=== Non-ISA 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 - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -18,11 +17,11 @@ |0.1 |2021-03-22 |Original draft |Gajinder Panesar, Arun Thomas and Greg Favor + |=== -==== Rationale +=== 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 +=== Definitions See the https://docs.google.com/presentation/d/1nQ5uFb39KA6gvUi5SReWfIQSiRN7hp6z7ZPfctE4mKk/edit?usp=sharing[extension @@ -33,7 +32,7 @@ lifecycle deck] for milestone definitions. The non-ISA DoD checklist contains both plan and status of non-ISA DoD tasks. -==== Policy +=== 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 @@ -84,7 +83,7 @@ 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 +==== List of tasks . Specification: content is complete, and approved by the task group + . Consistency cross-check. This is to ensure any new extensions that @@ -114,7 +113,7 @@ 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 +=== 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 index d1d73f3..e3056c1 100644 --- a/src/os_hypervisor_requirements.adoc +++ b/src/os_hypervisor_requirements.adoc @@ -1,5 +1,5 @@ [[os_hypervisor_requirements]] -=== OS & Hypervisor Requirements for Specification Ratification +== OS & Hypervisor Requirements for Specification Ratification *Version:* 0.1 + *One line description:* Provide a reference implementation (as a patchset) @@ -8,8 +8,7 @@ FreeRTOS/Zephyr. + *Author(s):* Philipp Tomsich + *Status:* Draft + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -20,7 +19,7 @@ FreeRTOS/Zephyr. + |=== -==== Rationale +=== Rationale This policy provides a reference implementation (as a patchset) providing basic enablement for the following (see `Plan Requirements'): @@ -54,7 +53,7 @@ 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 + +=== Policy + *Application Notes* + Application notes for the Plan milestone, Freeze milestone, and Approval-milestone follow. + @@ -66,7 +65,7 @@ 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 +==== Plan requirements * The group responsible for an extension shall create an `applicability & impact statement' for the extension, which details the software @@ -96,7 +95,7 @@ HC meeting) and received sign-off from the Software HC. + impact on the software ecosystem and whether independent evaluation and experimentation are possible with the proposed plan. -===== Freeze requirements +==== Freeze requirements * The proposed patches for the enablement have been sent to the communities governing the upstream projects identified in the Plan as @@ -110,13 +109,13 @@ an effective review and foster good community relations), + ** include a cover letter explaining the purpose of the extension, request a community review, and reference the frozen documentation -===== Ratification-ready requirements +==== 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 + +=== Transition to start using policy + Immediate diff --git a/src/platforms.adoc b/src/platforms.adoc index 8d41be5..faebd8b 100644 --- a/src/platforms.adoc +++ b/src/platforms.adoc @@ -1,5 +1,5 @@ [[platforms]] -=== Platforms +== Platforms NOTE: This policy is out-of-date but will not be updated until 2023. It is left here for historical reasons. @@ -9,8 +9,7 @@ It is left here for historical reasons. *Author(s):* Philipp Tomsich + *Status:* Approved + -==== Version History - +*Version History:* + [width="100%",cols="<15%,<15%,<40%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -37,7 +36,7 @@ leadership. |Philipp Tomsich |=== -==== Rationale +=== Rationale This document summarizes the policies and procedures adopted for RISC-V Platforms. @@ -53,7 +52,7 @@ All RISC-V Platforms are developed and released by the Platforms Horizontal Subcommittee, operating under the auspices of the Software Horizontal Committee. -===== Intended audience +==== Intended audience This policy document targets the following audiences: @@ -63,14 +62,14 @@ Subcommittee + * Architects and Integrators of software and hardware solutions for the RISC-V ecosystem -===== How to read this document +==== 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 +=== Policy A solid foundation for software development and interoperability is required to support the growth of the software ecosystem for RISC-V. @@ -94,7 +93,7 @@ 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 +==== Scope The focus of the platform standards is software-centric. However, both software and hardware will be affected by the requirements put forth in @@ -108,7 +107,7 @@ 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 +==== Specification coverage *The Platforms released must cover at least the following runtime environments:* @@ -146,7 +145,7 @@ 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 +==== Naming and Versioning *The full name of each platform shall be constructed as follows:* @@ -163,7 +162,7 @@ Platform 2022.3". *Only official Platforms released by RISC-V International can use the "RISC-V" prefix.* -===== Machine-readable identification and experimental versions +==== 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 @@ -180,7 +179,7 @@ cannot use `RISC-V' as part of their platform name)*. shall result in a valid URL that hosts the specification and ancillary documentation.* -===== Claiming Compatibility +==== Claiming Compatibility Products implementing a RISC-V Platform shall claim compatibility with a Platform and any applicable extensions that the product implements. @@ -234,7 +233,7 @@ 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 +==== Structure *Platforms consist of:* @@ -277,7 +276,7 @@ back to Requirements. + * *Rationales and application notes must reference the corresponding requirement or subclause*. -===== Deprecation of requirements +==== Deprecation of requirements Platforms address both _forward compatibility_ and _backward compatibility:_ @@ -310,7 +309,7 @@ requirement). products to drop the respective feature, as long as the feature is not incompatible with any new requirements.* -===== No non-obvious requirements +==== No non-obvious requirements Platforms will frequently reference third-party documents, specifications and standards. This introduces the risk of affecting @@ -323,7 +322,7 @@ 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* +=== 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 @@ -333,9 +332,9 @@ up to date with new Profiles. Amendments and new extensions are published as-needed. -==== Platforms Lifecycle +=== Platforms Lifecycle -===== Inception +==== Inception *A new platform specification or an extension can be proposed to the Platform HSC by:* @@ -356,18 +355,18 @@ 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 +==== 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 +==== Publication stage After approval by the Software HC, it is published and enters into immediate effect. -==== Retirement of Platforms +=== Retirement of Platforms Corrections are not issued to update information that has become outdated since publication. + @@ -376,7 +375,7 @@ version. + *In general, a correction will not be issued for a publication that is older than three years.* -==== Exceptions +=== Exceptions Implementations (both hardware and software) may decide not to be compatible with any Platform, as long as no misleading compatibility diff --git a/src/policy.adoc b/src/policy.adoc index cf78ffc..b62f9d0 100644 --- a/src/policy.adoc +++ b/src/policy.adoc @@ -1,13 +1,12 @@ [[policy]] -=== Policy +== Policy *Version:* 1.2 + *One line description:* How to propose, approve, and adopt policies + *Author(s):* Mark I Himelstein + *Status:* Approved + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -19,12 +18,12 @@ a TSC vote. |Stephano Cetola |=== -==== Rationale +=== Rationale We need to create and adopt policies to govern ourselves below the bylaws. -==== Policy +=== Policy . Use the policy template to propose a policy. All fields should be filled in. + @@ -43,11 +42,11 @@ all task/sig groups. + weekly meeting. Policies that affect things like voting must go through the TSC for final approval vote. -==== Exception handling + +=== 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 + +=== Transition to start using policy + Immediate diff --git a/src/profiles.adoc b/src/profiles.adoc index 31cd1c8..c554713 100644 --- a/src/profiles.adoc +++ b/src/profiles.adoc @@ -1,13 +1,12 @@ [[profiles]] -=== Profiles +== Profiles *Version:* 3.3 + *One line description:* Rules for profiles + *Author(s):* Mark Himelstein + *Status:* + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -19,11 +18,11 @@ |=== -==== Rationale +=== 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 +=== Definitions Organization acronyms can be found in the organization slide doc https://docs.google.com/presentation/d/1eEVuu6lRZd9iiDnZQSZME7Q7svtTG3pGIKHPmZ79B8E/edit?usp=sharing[here]. @@ -81,9 +80,9 @@ 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 +=== Policy -===== Profiles: +==== Profiles: . Profiles are defined and approved by the TSC. + . TSC should publish the updated roadmap by April 1 of each year, using @@ -128,7 +127,7 @@ are complete, and they pass the tests. + 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 +=== Transition to start using policy This will be the acting policy until approved (possibly with modifications before approval). @@ -139,7 +138,7 @@ is granted. All implementers and TGs must comply with the strings and versions described in this policy immediately. -==== Exceptions +=== Exceptions Profile naming and versioning exceptions must be approved by the TSC. diff --git a/src/question_response.adoc b/src/question_response.adoc index dd58499..0c36d97 100644 --- a/src/question_response.adoc +++ b/src/question_response.adoc @@ -1,5 +1,5 @@ [[question_response]] -=== Question Response +== Question Response *Version:* 1.1 + *One line description:* Answer member questions reliably within a SLA and @@ -7,8 +7,7 @@ identify who is responsible for ensuring questions are answered + *Author(s):* Mark I Himelstein + *Status:* Approved + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -19,7 +18,7 @@ identify who is responsible for ensuring questions are answered + |=== -==== Rationale +=== Rationale This is a best practice. We need this policy because when people ask questions to the general email lists sometimes no one responds. @@ -32,7 +31,7 @@ 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 +=== Policy This policy applies to any question from technical to procedural to resources etc. @@ -82,7 +81,7 @@ 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 + +=== Exception handling + Escalate to help@riscv.org if you don’t get a response after trying twice. diff --git a/src/ratification.adoc b/src/ratification.adoc index f520338..42e3bda 100644 --- a/src/ratification.adoc +++ b/src/ratification.adoc @@ -1,5 +1,5 @@ [[ratification]] -=== Ratfication +== Ratification *Version:* 1.7 + *One line description:* These are the rules governing the ratification @@ -7,8 +7,7 @@ of RISC-V Specifications + *Author(s):* Mark Himelstein, Stephano Cetola + *Status:* Approved + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -55,14 +54,14 @@ Stephano Cetola |=== -==== Rationale +=== 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 +=== Definitions _Initiator_: The requester of an extension or specification. @@ -111,7 +110,7 @@ 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 +=== Policy The ratification process starts with the lifecycle. Please see the lifecycle @@ -158,7 +157,7 @@ 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 +==== Plan Milestone * The Plan Milestone focuses on the planning activities for the specification including the schedule, resources and criteria which may @@ -171,7 +170,7 @@ presentation of the planning information. + 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 +==== 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 @@ -239,7 +238,7 @@ 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 +==== 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 @@ -283,7 +282,8 @@ extension in a new specification. HCs may approve any non-substantive changes (editing, formatting, clarifications, etc.) at any time in a ratified specification. -==== Exceptions +=== 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 index 81fd5aa..52b6538 100644 --- a/src/rationale.adoc +++ b/src/rationale.adoc @@ -1,13 +1,12 @@ [[rationale]] -=== 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 - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -17,7 +16,7 @@ |=== -==== Rationale +=== Rationale We have no common way to evaluate or understand the implications for part or all of proposed extensions or changes to existing ratified @@ -36,7 +35,7 @@ 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 + +=== 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 @@ -86,11 +85,11 @@ for the vector extension). + might otherwise expect? + .. Are there any unknowns or issues? -==== Exception handling + +=== Exception handling + All escalations go to the chair of the group, if unresolved then CTO, if unresolved then TSC. -==== Transition to start using policy + +=== Transition to start using policy + Start effective August 15, 2020. Specifications that are close to ratification/approval may not be able diff --git a/src/riscv_contributor.adoc b/src/riscv_contributor.adoc index 9db9520..6ef116e 100644 --- a/src/riscv_contributor.adoc +++ b/src/riscv_contributor.adoc @@ -1,13 +1,12 @@ [[riscv_contributor]] -=== RISC-V Contributor +== Contributor *Version:* 1.1 + *One line description:* Who can contribute to RISC-V specifications + *Author(s):* Mark Himelstein + *Status:* Approved + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -19,13 +18,13 @@ |=== -==== Rationale +=== 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 +=== Policy . Contributors to RISC-V specification text must have signed a member agreement. + @@ -43,8 +42,8 @@ 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 + +=== Exception handling + Not applicable -==== Transition to start using policy + +=== Transition to start using policy + Immediately diff --git a/src/riscv_tech_policies.adoc b/src/riscv_tech_policies.adoc index 116aa42..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,14 +72,47 @@ Copyright 2024 by RISC-V International. [preface] include::contributors.adoc[] +[preface] include::intro.adoc[] -include::approved.adoc[] -include::draft.adoc[] -include::archived.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 index 7b8ea8d..b0563d3 100644 --- a/src/sail_priv_spec_1_11.adoc +++ b/src/sail_priv_spec_1_11.adoc @@ -1,21 +1,20 @@ [[sail_priv_spec_1_11]] -=== SAIL Requirements for Privileged 1.11 Extensions +== 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:* Approved + - -==== Version History +*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 +=== Rationale SAIL modeling is required for all specifications being ratified under the governance of the Privileged ISA Committee . As SAIL modeling for @@ -27,13 +26,13 @@ https://docs.google.com/document/u/2/d/1Hp9ZZSzjk6Tp2pIvh33mNCj6wAoJCEqsdENQUTSr of Done] tasks related to SAIL until next year when suitable resources become available. -==== Policy +=== 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 +=== Transition to start using policy Immediate diff --git a/src/technical_voting.adoc b/src/technical_voting.adoc index aee8d85..7321e9a 100644 --- a/src/technical_voting.adoc +++ b/src/technical_voting.adoc @@ -1,14 +1,13 @@ [[technical_voting]] -=== Technical Voting Policy +== Technical Voting *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 + - -==== Version History +*Status:* Approved + +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -20,7 +19,7 @@ creation. At the TSC level. Cleaned up language. |Mark Himelstein |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 @@ -30,13 +29,13 @@ 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*. @@ -59,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*. @@ -77,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 index 9581684..d45e9df 100644 --- a/src/template.adoc +++ b/src/template.adoc @@ -10,37 +10,36 @@ To create a new policy, perform the following steps: [quote] ---- [[newname]] -=== New Policy Name +== New Policy Name *Version:* + *One line description:* + *Author(s):* + *Status:* + -==== Version History - +*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 +=== Rationale -==== Definitions +=== Definitions -==== Related documentation +=== Related documentation -==== Policy +=== Policy -==== Exception handling +=== Exception handling -==== Transition to start using policy +=== Transition to start using policy ---- diff --git a/src/universes.adoc b/src/universes.adoc index d64ec33..69f0eaa 100644 --- a/src/universes.adoc +++ b/src/universes.adoc @@ -1,5 +1,5 @@ [[universes]] -=== Universes +== Universes *Version:* 0.1 + *One line description:* An optional technical area that potentially @@ -7,8 +7,7 @@ pervasively impacts all specifications + *Author(s):* Mark Himelstein + *Status:* Draft + -==== Version History - +*Version History:* + [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -17,7 +16,7 @@ pervasively impacts all specifications + |=== -==== Rationale +=== Rationale There are optional technical areas like CHERI or GPUs that could potentially affect all or a pervasive amount of specifications. Rather @@ -38,7 +37,7 @@ 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 +=== Policy Establishing a Universe: @@ -91,11 +90,11 @@ 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 + +=== 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 + +=== 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 index 7231853..ae7bdd3 100644 --- a/src/versioning.adoc +++ b/src/versioning.adoc @@ -1,5 +1,5 @@ [[versioning]] -=== Versioning +== Versioning *Version:* 0.1 + *One line description:* Rules governing how we version RISC-V @@ -7,8 +7,6 @@ artifacts + *Author(s):* Philipp Tomsich, Stephano Cetola, Rafael Sene + *Status:* Draft + -==== Version History - [width="100%",cols="<5%,<15%,<50%,<20%",options="header",] |=== |Ver |Date |Details |Name(s) @@ -18,21 +16,21 @@ artifacts + |=== -==== Rationale +=== 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 +=== Policy -===== Versioning Standard +==== 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 +==== Version Structure We follow the X.Y.Z-STATUS: @@ -58,13 +56,13 @@ like +[build-date]. + 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 +=== Exception handling None. -==== Transition to start using policy + +=== Transition to start using policy + [TEXT or "Immediate on approval"] -==== Next steps +=== Next steps . ...