You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
UnifiedDB follows the RISC-V International Code of Conduct.
4
+
5
+
== Our Pledge
6
+
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socioeconomic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
7
+
8
+
== Our Standards
9
+
Examples of behavior that contributes to creating a positive environment include:
10
+
11
+
Using welcoming and inclusive language
12
+
Being respectful of differing viewpoints and experiences
13
+
Gracefully accepting constructive criticism
14
+
Focusing on what is best for the community
15
+
Showing empathy towards other community members
16
+
Examples of unacceptable behavior by participants include:
17
+
18
+
The use of sexualized language or imagery and unwelcome sexual attention or advances
19
+
Trolling, insulting/derogatory comments, and personal or political attacks
20
+
Trafficking in disinformation, unsubstantiated slanderous rumors, and conspiracy theories
21
+
Public or private harassment
22
+
Publishing others' private information, such as a physical or electronic address, without explicit permission
23
+
Other conduct which could reasonably be considered inappropriate in a professional setting
24
+
Our Responsibilities
25
+
RISC-V International is responsible for clarifying the standards of acceptable behavior and is expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. RISC-V International has the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
26
+
27
+
== Scope
28
+
This Code of Conduct applies within all project spaces, and it also applies when an individual is representing the project or its community in public spaces. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
29
+
30
+
== Enforcement
31
+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting RISC-V International at [email protected]. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. RISC-V International is obligated to maintain confidentiality with regard to the reporter of an incident.
32
+
33
+
== Enforcement Guidelines
34
+
RISC-V International will follow these guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
35
+
36
+
=== 1. Correction
37
+
Community Impact:: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
38
+
39
+
Consequence:: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. Moderation of postings may be used if applicable.
40
+
41
+
=== 2. Warning
42
+
Community Impact:: A violation through a single incident or series of actions.
43
+
44
+
Consequence:: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
45
+
46
+
=== 3. Temporary Ban
47
+
Community Impact:: A serious violation of community standards, including sustained inappropriate behavior.
48
+
49
+
Consequence:: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
50
+
51
+
=== 4. Permanent Ban
52
+
Community Impact:: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
53
+
54
+
Consequence:: A permanent ban from any sort of public interaction within the community.
55
+
56
+
== Attribution
57
+
This Code of Conduct is based on the https://www.contributor-covenant.org/version/2/1/code_of_conduct/[Contributor Covenant, version 2.1]. For answers to common questions about this code of conduct, see the Contributor Covenant https://www.contributor-covenant.org/faq[FAQ].
The latest documentation artifacts generated from the HEAD of main, include ISA manuals, profiles, etc.,
6
-
can be found https://riscv-software-src.github.io/riscv-unified-db/index.html[on the GitHub pages site].
7
-
8
-
== Overview
9
-
10
-
The RISC-V Unified Database is intended to hold *all* the information needed to describe RISC-V,
11
-
including a list of extensions, instruction specifications, CSR specifications, and documentation prose. The vision is that anything one would need for RISC-V can be generated from the information in this repository.
12
-
13
-
This repository contains:
3
+
[WARNING]
4
+
----
5
+
This project is under rapid development. Expect schemas and APIs to change.
14
6
15
-
* A (eventually complete) description of the RISC-V specification in a machine-readable format.
16
-
* A tool to generate multiple views of that spec, including:
17
-
** A configuration-specific, human-readable documentation webpage
18
-
** [COMING SOON] A configuration-specific Instruction Set Simulator
19
-
** More backends are planned
7
+
The data in the `arch` directory is also a work in progress and may be incorrect. As subsets of the
* Generate https://riscv-software-src.github.io/riscv-unified-db/manual/html/index.html[configuration-specific documentation] tailored to the set of implemented extensions and unnamed implementation options (_e.g._, `./do gen:html[example_rv64_with_overlay]`).
26
-
** Only implemented extensions/instructions/CSRs are included
27
-
** Unreachable/unimplemented parts of the formal specification are pruned away
28
-
** A dedicated documentation page for every implemented instruction, including its encoding, pruned execution behavior, and what types of exceptions it may cause.
29
-
** A dedicated documentation page for every implemented CSR, including its (possibly runtime-changing) encoding, fields, and pruned behavior on reads and writes
30
-
** Clickable links to all mentions of instructions, extensions, CSRs, CSR fields, and glossary terms.
31
-
* Generate documentation for specific extensions (_e.g._, `./do gen:ext_pdf[B]`)
32
-
** Automatically include a complete list of added instructions and CSRs
33
-
** Per-instruction documentation
34
-
** Per-CSR documentation
35
-
** Formal specification
36
-
* Generate a single YAML file containing *everything* knowable about a configuration (_e.g._, `./do gen:cfg_arch[example_rv64_with_overlay]`).
23
+
== Overview
37
24
38
-
=== Possibilities:
25
+
The goal of the RISC-V Unified Database (UnifiedDB/UDB) is to hold *all* the information needed to describe RISC-V,
26
+
including a list of extensions, instruction specifications, CSR specifications, and documentation prose. The vision is that anything one would need for RISC-V can be generated from the information in this repository.
* Generate the full RISC-V specification, along with an appendix of instructions and CSRs
44
-
* ...
28
+
In addition to storing the data, UnifiedDB also provides many tools that use the data to generate
29
+
artifacts such as specification documents, toolchain inputs, and simulators.
45
30
46
-
== Prerequisites
31
+
UnifiedDB is an open-source, worldwide project.
32
+
Contributors do not need to be members of https://riscv.org[RISC-V International (RVI)],
33
+
though maintainers discuss strategic direction and coordinate with the RISC-V standard through the
34
+
https://lf-riscv.atlassian.net/wiki/x/iwCsCw?atlOrigin=eyJpIjoiYzU3N2ZiNDViMGRkNGE3ODg0ODVlOWU5YzgzYWM2ODMiLCJwIjoiYyJ9[UnifiedDB Special Interest Group (UDB SIG)] at RVI.
47
35
48
-
There are two supported ways to run the RISC-V Unified Database,
49
-
both of which are container-based.
36
+
== Repository structure
50
37
51
-
=== Singularity/Apptainer
38
+
The following directories contain information relevant to most users of UnifiedDB
52
39
53
-
You can run within `Singularity CE` (>= 3.3) or `Apptainer` (>= 1.0) container system. Either one will work (they are forks).
40
+
* `arch`: The RISC-V standard
41
+
* `arch_overlay`: Non-standard RISC-V extensions
42
+
* `cfgs`: Configurations used by backends to customize generated outputs
43
+
* `schemas`: Data schemas for the content in `arch`
54
44
55
-
If it is not installed, either ask your IT admin or:
45
+
Additionally, developers will be interested in the following:
56
46
57
-
* For Apptainer, see https://apptainer.org/docs/admin/main/installation.html[Apptainer Installation].
58
-
* For Singularity CE, see https://docs.sylabs.io/guides/latest/admin-guide/installation.html[Singularity CE Installation].
47
+
* `backends`: Tools to generate artifacts (documents, simulators, etc.) from UDB data
48
+
* `bin`: Wrapper scripts to run commands within the container enviornment
49
+
* `lib`: Scripts (mostly Ruby) to read/interact with UDB data
59
50
60
-
[NOTE]
61
-
You do *not* need root privileges to download or use the container. However, to modify/build the container,
62
-
you will need either root privileges or the ability to run in `fakeroot` mode. See https://docs.sylabs.io/guides/4.1/user-guide/fakeroot.html[Singularity Fakeroot Documentation] for more information.
51
+
== Getting Started
63
52
64
-
When you run with Singularity/Apptainer, the files under `bin/`
UnifiedDB tools are set up to run in a container. Both Docker (any version) and Singularity/Apptainer (`Singularity CE >= 3.3` or `Apptainer >= 1.0`) are supported.
71
56
72
57
=== Devcontainer
73
58
@@ -87,26 +72,21 @@ You can then run `Dev Containers: Open Folder in Container...` from the Command
87
72
88
73
You can start a GitHub Codespace for this repository by clicking the "Code" button and selecting "Open with Codespaces".
89
74
90
-
== Tasks
75
+
=== Tasks
91
76
92
-
Quick start:
77
+
UnifiedDB uses https://github.com/ruby/rake[Rake], a Ruby-based Makefile alternative, to manage tasks.
78
+
For convienence, running Rake inside the container is encapulated in `do`. For example:
93
79
94
80
[source,bash]
95
81
----
96
82
./do --tasks # list all documented tasks
83
+
./do --desc gen:html_manual # describe the 'gen:html_manual' task in more detail
97
84
98
-
## examples
99
-
100
-
# run smoke tests
101
-
./do test:smoke
85
+
./do test:smoke # run smoke tests
102
86
103
87
# generate all versions of ISA manual, as an Antora static website
104
88
./do gen:html_manual MANUAL_NAME=isa VERSIONS=all
105
89
106
90
# generate an implementation-specific spec for the 'example_rv64_with_overlay' config
0 commit comments