[doc] Use consistent spelling/capitalization of names
Consistently use the following spelling for document formats,
programming languages, and names:
- Markdown
- Hjson
- JSON
- Verilog
- HTML
- GitHub
- CSS
- Python
Also avoid abbreviations:
- repo -> repository
Signed-off-by: Philipp Wagner <phw@lowrisc.org>
diff --git a/doc/project/checklist.md b/doc/project/checklist.md
index 536374c..37bb112 100644
--- a/doc/project/checklist.md
+++ b/doc/project/checklist.md
@@ -92,7 +92,7 @@
### STYLE_X
-Confirming to style guide regarding X usage. TODO: Related Github issue.
+Confirming to style guide regarding X usage. TODO: Related GitHub issue.
### LINT_PASS
diff --git a/doc/project/hw_stages.md b/doc/project/hw_stages.md
index 961073e..e0bba83 100644
--- a/doc/project/hw_stages.md
+++ b/doc/project/hw_stages.md
@@ -29,7 +29,7 @@
Once the specification has been shared with the OpenTitan audience and sufficient review has been completed, this phase is exited.
The next life stage is **Development**.
-The hardware IP is being developed in GitHub, the specification is converted to markdown, and design and verification planning is underway.
+The hardware IP is being developed in GitHub, the specification is converted to Markdown, and design and verification planning is underway.
This is a long phase expected to last until a more formal review is requested for full completion signoff.
When in Development phase, the stage tracking of the design and verification milestones are valid.
See those sections that follow for details there.
diff --git a/doc/rm/comportability_specification/index.md b/doc/rm/comportability_specification/index.md
index d068955..54e5fd1 100644
--- a/doc/rm/comportability_specification/index.md
+++ b/doc/rm/comportability_specification/index.md
@@ -56,9 +56,9 @@
// SPDX-License-Identifier: Apache-2.0
```
-The project has adopted [Hjson](https://hjson.org) for json files, extending json to allow comments.
+The project has adopted [Hjson](https://hjson.org) for JSON files, extending JSON to allow comments.
Thus the Hjson files can include the header above.
-If pure json must be used for some reason, the "SPDX-License-Identifier:" can be added as the first key after the opening "{".
+If pure JSON must be used for some reason, the "SPDX-License-Identifier:" can be added as the first key after the opening "{".
Tools developed by the project should accept and ignore this key.
### Coding Style
diff --git a/doc/rm/hjson_usage_style.md b/doc/rm/hjson_usage_style.md
index 477a0ba..5322aa7 100644
--- a/doc/rm/hjson_usage_style.md
+++ b/doc/rm/hjson_usage_style.md
@@ -7,7 +7,7 @@
### Summary
Json files are used to provide input data to many of the tools.
-The preference is to use [Hjson](https://hjson.org/), which is a variation of regular json that is easier to write.
+The preference is to use [Hjson](https://hjson.org/), which is a variation of regular JSON that is easier to write.
In particular it allows the quote marks to be left off the key names, it allows a single string to be quoted with triple quote marks and flow over multiple lines (which is often needed in text descriptions) and it allows comments using the # or // style.
This guide covers the enhancements provided by Hjson that are used in the project along with a recommended style.
@@ -42,8 +42,8 @@
## Hjson file format
-Hjson is a variation of regular json that is easier to write.
-There are parsers in a number of languages and the tools make extensive used of the `hjson` package provided for Python3.
+Hjson is a variation of regular JSON that is easier to write.
+There are parsers in a number of languages and the tools make extensive used of the `hjson` package provided for Python 3.
A full description can be found on the [Hjson website](https://hjson.org/), but the main features that make it convenient are that it keeps files cleaner by allowing the quote marks to be left off the key names, it enables long descriptive text by allowing a single string to flow over multiple lines and it allows comments using the # or // style.
For example:
@@ -84,7 +84,7 @@
}
```
-In cases where the file may need to be parsed by a standard json parser the comments must be omitted, but the SPDX license information should be provided as a top-level key/value using pure json syntax and ignored by any tool.
+In cases where the file may need to be parsed by a standard JSON parser the comments must be omitted, but the SPDX license information should be provided as a top-level key/value using pure JSON syntax and ignored by any tool.
```json {.good}
@@ -102,7 +102,7 @@
Single entries are of the form `key: "value"` Keys must be alphanumeric strings and should not be in quotes.
(Hjson allows this.
-The quotes may be included as an exception to the style guide if there is an expectation that the file needs to be parsed with a more traditional json parser.)
+The quotes may be included as an exception to the style guide if there is an expectation that the file needs to be parsed with a more traditional JSON parser.)
The valid keys for each tool are described in the tool documentation.
The style is for a simple value to be in quotes (even if it is a number) and the tool should manage any type conversions.
diff --git a/doc/rm/markdown_usage_style.md b/doc/rm/markdown_usage_style.md
index d137d0b..35f9f98 100644
--- a/doc/rm/markdown_usage_style.md
+++ b/doc/rm/markdown_usage_style.md
@@ -7,9 +7,9 @@
### Summary
Markdown files are used to write most documentation.
-The main markdown tool is [Hugo](https://gohugo.io).
+The main Markdown tool is [Hugo](https://gohugo.io).
-The markdown processing is done using the `build_docs.py` tool in the `util` directory.
+The Markdown processing is done using the `build_docs.py` tool in the `util` directory.
As with all style guides the intention is to:
@@ -43,10 +43,10 @@
### Line length
-There are two acceptable styles for line wrapping in markdown files:
+There are two acceptable styles for line wrapping in Markdown files:
1. Wrap lines at under 80 characters.
- This ensures that the source is readable without any markdown processing, but re-wrapping a paragraph after an insertion or deletion tends to cause more diffs when the change is reviewed.
+ This ensures that the source is readable without any Markdown processing, but re-wrapping a paragraph after an insertion or deletion tends to cause more diffs when the change is reviewed.
When making changes to a document using this style consider allowing short lines rather than a full re-wrap after minor edits.
Then occasionally a separate commit can be used that only does re-wrapping of the paragraphs.
This style is recommended for all README files.
@@ -60,7 +60,7 @@
Headings and sections are given ID tags to allow cross references.
The ID is the text of the heading, converted to lower case and with spaces converted to `-`.
-Thus `### Headings and sections` gets the ID `headings-and-sections` and can be referenced using the markdown hyperlink syntax `[link text](#headings-and-sections)`.
+Thus `### Headings and sections` gets the ID `headings-and-sections` and can be referenced using the Markdown hyperlink syntax `[link text](#headings-and-sections)`.
Headings and sections are added to the table of contents.
@@ -84,21 +84,21 @@
### Text Format
-Where possible, please restrict markdown text to the ASCII character set to avoid downstream tool issues.
+Where possible, please restrict Markdown text to the ASCII character set to avoid downstream tool issues.
Unicode may be used when referring to proper names.
### Comments
Comments are rare, but should be used where needed.
-Use the html `<!--` and `-->` as the comment delimiters.
+Use the HTML `<!--` and `-->` as the comment delimiters.
### Markdown file extensions
-The markdown files should use the `.md` file extension.
+The Markdown files should use the `.md` file extension.
## Markdown file format for IP module descriptions
-Typically the markdown file for an IP block follows the same outline.
+Typically the Markdown file for an IP block follows the same outline.
The header instantiates the standard document header and reads the Hjson description of the module.
diff --git a/doc/rm/python_coding_style.md b/doc/rm/python_coding_style.md
index 3f4dcc5..c17bdc5 100644
--- a/doc/rm/python_coding_style.md
+++ b/doc/rm/python_coding_style.md
@@ -67,8 +67,8 @@
### Lint tool
-The `lintpy.py` utility in `util` can be used to check python code.
-It checks all python (`.py`) files that are modified in the local repo and will report problems.
+The `lintpy.py` utility in `util` can be used to check Python code.
+It checks all Python (`.py`) files that are modified in the local repository and will report problems.
Both `yapf` and `isort` checks are run.
Basic lintpy usage is just to run from the util directory.
@@ -90,7 +90,7 @@
```
Errors may be fixed using the same tool to edit the problem file(s) in-place (you may need to refresh the file(s) in your editor after doing this).
-This uses the same set of files as are being checked, so unless the`--file` or `-f` flag is used this will only affect files that have already been modifed (or staged for commit if `-c`is used) and will not fix errors in python files that have not been touched.
+This uses the same set of files as are being checked, so unless the`--file` or `-f` flag is used this will only affect files that have already been modifed (or staged for commit if `-c`is used) and will not fix errors in Python files that have not been touched.
```console
$ cd $REPO_TOP/util
@@ -117,7 +117,7 @@
$ isort file.py
```
-Yapf and isort are python packages and should be installed with pip:
+Yapf and isort are Python packages and should be installed with pip:
```console
$ pip3 install --user yapt
@@ -171,9 +171,9 @@
Do not use tabs.
You should set your editor to emit spaces when you hit the tab key.
-### Executable python tools
+### Executable Python tools
-Tools that can be executed should use `env` to avoid making assumptions about the location of the python interpreter.
+Tools that can be executed should use `env` to avoid making assumptions about the location of the Python interpreter.
Thus they should begin with the line:
```console
@@ -190,5 +190,5 @@
This will provide support for `--help` and `-h` to get usage information.
Every command line program should provide `--version` to provide standard version information.
-This lists the git repositary information for the tool and the version numbers of any python packages that are used.
+This lists the git repositary information for the tool and the version numbers of any Python packages that are used.
The `show_and_exit` routine in `reggen/version.py` can be used to do this.
diff --git a/doc/rm/register_tool/index.md b/doc/rm/register_tool/index.md
index 723fa29..2032370 100644
--- a/doc/rm/register_tool/index.md
+++ b/doc/rm/register_tool/index.md
@@ -3,13 +3,13 @@
---
The register tool is used to construct register documentation, register RTL and header files.
-It is either used stand-alone or by being invoked as part of markdown processing.
+It is either used stand-alone or by being invoked as part of Markdown processing.
## Running standalone regtool.py
-The standalone `regtool.py` is a python3 tool to read configuration and register descriptions in Hjson and generate various output formats.
-Currently it can output html documentation, standard json, compact standard json (whitespace removed), Hjson, verilog RTL and various forms of C header files.
+The standalone `regtool.py` is a Python 3 tool to read configuration and register descriptions in Hjson and generate various output formats.
+Currently it can output HTML documentation, standard JSON, compact standard JSON (whitespace removed), Hjson, Verilog RTL and various forms of C header files.
The standard `--help` and `--version` command line flags are supported to print the usage and version information.
Because the version includes information on libraries (which may be different between systems) reporting the version output is sometimes useful when issues are reported.
@@ -22,12 +22,12 @@
The tool input is an Hjson file containing the Comportable description of the IP block and its registers.
-A description of Hjson (a varient of json) and the recommended style is in the [Hjson Usage and Style Guide]({{< relref "hjson_usage_style.md" >}}).
+A description of Hjson (a variant of JSON) and the recommended style is in the [Hjson Usage and Style Guide]({{< relref "hjson_usage_style.md" >}}).
The tables below describe valid keys for each context.
-It is an error if *required* keys are missing from the input json.
+It is an error if *required* keys are missing from the input JSON.
*Optional* keys may be provided in the input file as needed, as noted in the tables the tool may insert them (with default or computed values) during validation so the output generators do not have to special case them.
-Keys marked as "inserted by tool" should not be in the input json (they will be silently overwritten if they are there), they are derived by the tool during validation of the input and available to the output generators.
+Keys marked as "inserted by tool" should not be in the input JSON (they will be silently overwritten if they are there), they are derived by the tool during validation of the input and available to the output generators.
{{% selfdoc "reggen" %}}
@@ -220,7 +220,7 @@
This section details the register generation for hardware instantiation.
The input to the tool for this generation is the same `.hjson` file described above.
-The output is two verilog files that can be instantiated by a peripheral that follows the [Comportability Guidelines]({{< relref "comportability_specification" >}}).
+The output is two Verilog files that can be instantiated by a peripheral that follows the [Comportability Guidelines]({{< relref "comportability_specification" >}}).
The register generation tool will generate the RTL if it is invoked with the `-r` flag.
The `-t <directory>` flag is used to specify the output directory where the two files will be written.
@@ -626,5 +626,5 @@
## Generating documentation
-The register tool can be used standalone to generate html documentation of the registers.
-However, this is normally done as part of the markdown documentation using the special tags to include the register definition file and insert the configuration and register information.
+The register tool can be used standalone to generate HTML documentation of the registers.
+However, this is normally done as part of the Markdown documentation using the special tags to include the register definition file and insert the configuration and register information.
diff --git a/doc/rm/topgen_tool.md b/doc/rm/topgen_tool.md
index cc6f459..f83cf44 100644
--- a/doc/rm/topgen_tool.md
+++ b/doc/rm/topgen_tool.md
@@ -106,8 +106,8 @@
configurations
--top-only If defined, the tool generates top RTL only
--xbar-only If defined, the tool generates crossbar RTLs only
- --plic-only If defined, the tool generates RV_PLIC RTL and hjson only
- --hjson-only If defined, the tool generates complete hjson only
+ --plic-only If defined, the tool generates RV_PLIC RTL and Hjson only
+ --hjson-only If defined, the tool generates complete Hjson only
--top_ral, -r If set, the tool generates top level RAL model for DV
```
diff --git a/doc/ug/design.md b/doc/ug/design.md
index a2886ac..3ef0e4f 100644
--- a/doc/ug/design.md
+++ b/doc/ug/design.md
@@ -43,13 +43,13 @@
Documentation is a critical part of any design methodology.
Within the OpenTitan project there are two important tooling components to efficient and effective documentation.
-The first is the [Hugo](https://gohugo.io) tool, which converts an annotated markdown file into a rendered HTML file (including this document).
+The first is the [Hugo](https://gohugo.io) tool, which converts an annotated Markdown file into a rendered HTML file (including this document).
See the linked manual for information about the annotations and how to use it to create enhanced auto-generated additions to standard Markdown files.
The second is the [reggen]({{< relref "doc/rm/register_tool" >}}) register tool that helps define the methodology and description language for specifying hardware registers.
These descriptions are fed into docgen through annotations and ensure that the technical specifications for the IP are accurate and up to date with the hardware being built.
-Underlying and critical to this tooling is the human-written content that goes into the source markdown and register descriptions.
+Underlying and critical to this tooling is the human-written content that goes into the source Markdown and register descriptions.
Clarity and consistency is key.
See the [Markdown Style Guide]({{< relref "doc/rm/markdown_usage_style.md" >}}) for details and guidelines on the description language.
diff --git a/doc/ug/directory_structure.md b/doc/ug/directory_structure.md
index 77bb24d..95e2332 100644
--- a/doc/ug/directory_structure.md
+++ b/doc/ug/directory_structure.md
@@ -2,7 +2,7 @@
title: "Directory Structure"
---
-This document provides an overview of the opentitan repo directory structure.
+This document provides an overview of the opentitan repository directory structure.
The hierarchy underneath the root is fairly self explanatory, containing the following:
* `doc`: High level documentatation, user guides and reference manuals
* `util`: Helper scripts and generator tools
diff --git a/doc/ug/dv_methodology.md b/doc/ug/dv_methodology.md
index 2fd1ad8..7bfe9db 100644
--- a/doc/ug/dv_methodology.md
+++ b/doc/ug/dv_methodology.md
@@ -15,7 +15,7 @@
* Formal Property Verification (FPV)
For running dynamic simulations, the strategy is to use the [UVM1.2 methodology](https://www.accellera.org/downloads/standards/uvm) on top of a foundation of SystemVerilog based verification to develop constrained-random functional tests.
-Each DUT will include within the repo, a UVM testbench, a testplan, DV plan, a suite of tests, and a method to build, run tests and report the current status.
+Each DUT will include within the repository, a UVM testbench, a testplan, DV plan, a suite of tests, and a method to build, run tests and report the current status.
For FPV, some DUTs may also include an SV testbench along with design properties captured in the SystemVerilog Assertions (SVA) language.
As the project is still in development, the current status will not be completed for all IP, but that is the ultimate goal.
See discussion below on tracking progress.
@@ -66,7 +66,8 @@
### DV Plan
-The DV plan document captures the overall strategy, intent, the testbench block diagram, a list of interfaces / agents, VIPs, reference models, the functional coverage model, assertions and checkers. It also covers FPV goals, if applicable. This is written in [markdown]({{< relref "doc/rm/markdown_usage_style" >}}) and is made available in the corresponding `doc` directory of each DUT.
+The DV plan document captures the overall strategy, intent, the testbench block diagram, a list of interfaces / agents, VIPs, reference models, the functional coverage model, assertions and checkers. It also covers FPV goals, if applicable.
+This is written in [Markdown]({{< relref "doc/rm/markdown_usage_style" >}}) and is made available in the corresponding `doc` directory of each DUT.
A [template]({{< relref "hw/dv/doc/dv_plan_template" >}}) for the DV plan documentation as well as the testbench block diagram in the OpenTitan team drive (under the 'design verification' directory) are available to help get started.
@@ -96,7 +97,7 @@
The UVM RAL model for DUTs containing CSRs is auto-generated using the [reggen]({{< relref "util/reggen/README.md" >}}) tool.
The specification for capturing the CSRs in the Hjson format can be found in the [Register Tool]({{< relref "doc/rm/register_tool" >}}) documentation.
We currently check-in the auto-generated UVM RAL model along with our UVM testbench code and rely on CI checks for consistency.
-In future, we may move to a flow where it is not checked into the repo, but auto-generated on-the-fly as a part of the simulation.
+In future, we may move to a flow where it is not checked into the repository, but auto-generated on-the-fly as a part of the simulation.
### Testbench Automation
diff --git a/doc/ug/getting_started_design.md b/doc/ug/getting_started_design.md
index 4c76710..43423e4 100644
--- a/doc/ug/getting_started_design.md
+++ b/doc/ug/getting_started_design.md
@@ -42,7 +42,7 @@
The content and the status of the proposal can be shared with the team.
An example of a canonical detailed specification is the pinmux specification which can be found in the TeamDrive under TechnicalSpecifications --> deprecated, for those that have access to that resource.
-(Google Docs that have been converted into markdown on GitHub are archived here).
+(Google Docs that have been converted into Markdown on GitHub are archived here).
## Specification Publication
@@ -57,28 +57,26 @@
In parallel with publication and review of the specification, the initial skeleton design can commence.
There are many ways to get past this "big bang" of necessary implementation and get it through eventual code review.
One recommended method is as follows:
-* Start with a skeleton that includes a complete or near-complete definition of the register content in .hjson format
-* Combine with a basic markdown including that file
-* Combine with an IP-top-level verilog module that instantiates the auto-generated register model (see the [register tool documentation]({{< relref "../rm/register_tool" >}})), includes all of the known IP-level IO, clocking and reset.
+* Start with a skeleton that includes a complete or near-complete definition of the register content in Hjson format
+* Combine with a basic Markdown including that file
+* Combine with an IP-top-level Verilog module that instantiates the auto-generated register model (see the [register tool documentation]({{< relref "../rm/register_tool" >}})), includes all of the known IP-level IO, clocking and reset.
This is not mandatory but allows the basics to come in first with one review, and the full custom details over time.
Regardless the first check-ins of course should be compilable, syntax error free,
[coding style guide](https://github.com/lowRISC/style-guides/blob/master/VerilogCodingStyle.md)
friendly, [Comportability]({{< relref "../rm/comportability_specification" >}}) equivalent, etc., as indicated by the [design methodology user guide]({{< relref "design.md" >}}).
-A good example of an initial skeleton design can be seen in
-[Pull Request #166](https://github.com/lowRISC/opentitan/pull/166)
-for the AES module.
+A good example of an initial skeleton design can be seen in [Pull Request #166](https://github.com/lowRISC/opentitan/pull/166) for the AES module.
-As part of the GitHub filing process, the Google Doc specification must be converted into a markdown specification.
-(Tip: there are Google Doc add-ons that can convert the specification into markdown format).
+As part of the GitHub filing process, the Google Doc specification must be converted into a Markdown specification.
+(Tip: there are Google Doc add-ons that can convert the specification into Markdown format).
Once this is completed, any specifications on the Team Drive should be moved to the deprecated section of the drive, with a link at the top indicating that the document is for historical purposes only.
This applies only for those specifications that originated on the Drive.
## Full Design
-As the design develops within the OpenTitan repo, it transitions into "D0", "D1", etc., [design stages]({{< relref "doc/project/hw_stages.md" >}}) and will be eventually plugged into the top level.
+As the design develops within the OpenTitan repository, it transitions into "D0", "D1", etc., [design stages]({{< relref "doc/project/hw_stages.md" >}}) and will be eventually plugged into the top level.
Following the recommended best practices for digestible pull requests suggests that continuing to stage the design from the initial skeleton into the full featured design is a good way to make steady progress without over-burdening the reviewers.
## Top Level Inclusion
diff --git a/doc/ug/getting_started_verilator.md b/doc/ug/getting_started_verilator.md
index 096b35a..89480a6a 100644
--- a/doc/ug/getting_started_verilator.md
+++ b/doc/ug/getting_started_verilator.md
@@ -148,7 +148,7 @@
## DPI Source
The I/O interfaces described above are implemented using the DPI interface to Verilator.
-The code for these is stored in the repo at `hw/dv/dpi` with a sub-directory for each module.
+The code for these is stored in the repository at `hw/dv/dpi` with a sub-directory for each module.
There should be a fusesoc `.core` file in each sub-directory.
## Generating waveforms
diff --git a/doc/ug/github_notes.md b/doc/ug/github_notes.md
index 04ca7e5..30f8db2 100644
--- a/doc/ug/github_notes.md
+++ b/doc/ug/github_notes.md
@@ -11,10 +11,10 @@
## Getting a working repository
-To develop in the repo you will need to get a copy on your local
+To develop in the repository you will need to get a copy on your local
machine. To allow contributions to be made back to the main repo
(through a process called a Pull Request) you need to first make your
-own copy of the repo on GitHub then transfer that to your local
+own copy of the repository on GitHub then transfer that to your local
machine.
You will need to log in to GitHub, go to the [opentitan repository](https://github.com/lowRISC/opentitan) and click on
@@ -48,11 +48,11 @@
$ git config --global credential.helper 'cache --timeout=3600'
```
-Now make a local copy of your GitHub copy of the repo and let git know
+Now make a local copy of your GitHub copy of the repository and let git know
that it is derived from the **upstream** lowRISC repo:
```console
-$ cd <where the repo should go>
+$ cd <where the repository should go>
$ git clone https://github.com/$GITHUB_USER/opentitan.git
$ cd opentitan
$ git remote add upstream https://github.com/lowRISC/opentitan.git
@@ -64,8 +64,8 @@
lowRISC one as **upstream**. Making this link will allow you to keep your
local and GitHub repos up to date with the lowRISC one.
-If you want a different email address (or name) for the lowRISC repo then
-you can set it locally in the repo (similar to above but without the
+If you want a different email address (or name) for the lowRISC repository then
+you can set it locally in the repository (similar to above but without the
--global flag). This command must be executed from a directory inside
the local copy of the repo. (There is no need for the first `cd` if
you are following the previous step.)
@@ -78,9 +78,9 @@
## Working in your local repo
-The repo that you have created locally will initially be on the
+The repository that you have created locally will initially be on the
**master** branch. In general you should not make changes on this
-branch, just use it to track your GitHub repo and synchronize with the
+branch, just use it to track your GitHub repository and synchronize with the
lowRISC master repo.
The typical workflow is to make your own branch which it is
@@ -94,7 +94,7 @@
The status will initially indicate there are no changes, but as you
add, delete or edit files it will let you know the state of things.
-Once you are happy with your changes, commit them to the local repo by adding the files to the changes (if things are clean you can add using `git commit -a -s` instead of a number of `add` commands):
+Once you are happy with your changes, commit them to the local repository by adding the files to the changes (if things are clean you can add using `git commit -a -s` instead of a number of `add` commands):
```console
$ git add...
@@ -123,20 +123,20 @@
When you have finished everything locally (it is good practice to do a
status check to ensure things are clean) you can push your branch (eg
-forchange) to **your** GitHub repo (the **origin**):
+forchange) to **your** GitHub repository (the **origin**):
```console
$ git status
$ git push origin forchange
```
-Then you need to go to your repo in Github and either select branch
+Then you need to go to your repository in GitHub and either select branch
from the pulldown or often there is a status message that you can
click on, review the changes and make a Pull Request. You can add
reviewers and get your change reviewed.
If you need to make changes to satisfy the reviews then you do that in
-your local repo on the same branch. You will need to `add` files and
+your local repository on the same branch. You will need to `add` files and
commit again. It is normally best to squash your changes into a single
commit by doing it with `--amend` which will give you a chance to edit
the message. If you do this you need to force `-f` the push back to
@@ -151,7 +151,7 @@
Once the reviewers are happy you can "Rebase and Merge" the Pull
Request on GitHub, delete the branch there (it offers to do this when
-you do the merge). You can delete the branch in your local repo with:
+you do the merge). You can delete the branch in your local repository with:
```console
$ git checkout master
@@ -169,7 +169,7 @@
Then, an editor will open. Follow the instructions given there, to reorder and
combine commits, or to change the commit message. Then update the PR branch in
-the Github remote repository.
+the GitHub remote repository.
```console
$ git push -f origin HEAD
@@ -193,11 +193,11 @@
$ chmod +x .git/hooks/prepare-commit-msg
```
-## Update your repo with changes in the lowRISC repo
+## Update your repository with changes in the lowRISC repo
There is a little work to do to keep everything in sync. Normally you
-want to first get your local repo master branch up to date with the
-lowRISC repo (**upstream**) and then you use that to update your GitHub
+want to first get your local repository master branch up to date with the
+lowRISC repository (**upstream**) and then you use that to update your GitHub
copy (**origin**).
```console
@@ -250,7 +250,7 @@
```console
$ git rebase master
First, rewinding head to replay your work on top of it...
-Applying: [util][pystyle] Clean python style in single file tools
+Applying: [util][pystyle] Clean Python style in single file tools
Using index info to reconstruct a base tree...
M util/diff_generated_util_output.py
M util/build_docs.py
@@ -259,7 +259,7 @@
CONFLICT (content): Merge conflict in util/build_docs.py
Auto-merging util/diff_generated_util_output.py
error: Failed to merge in the changes.
-Patch failed at 0001 [util][pystyle] Clean python style in single file tools
+Patch failed at 0001 [util][pystyle] Clean Python style in single file tools
Use 'git am --show-current-patch' to see the failed patch
Resolve all conflicts manually, mark them as resolved with
@@ -277,7 +277,7 @@
After executing this command you are back to a clean tree with your
changes intact, but they are still based on whatever the earlier state
-of the repo was. Normally you will have to resolve the conflict
+of the repository was. Normally you will have to resolve the conflict
sometime, but the escape hatch can be useful if you don't have time
immediately!
@@ -297,7 +297,7 @@
=======
import docgen
import livereload
->>>>>>> [util][pystyle] Clean python style in single file tools
+>>>>>>> [util][pystyle] Clean Python style in single file tools
```
@@ -340,7 +340,7 @@
```console
$ git add build_docs.py
$ git rebase --continue
-Applying: [util][pystyle] Clean python style in single file tools
+Applying: [util][pystyle] Clean Python style in single file tools
```
If there were more than one patch outstanding (which isn't usual if
@@ -359,7 +359,7 @@
Author: Mark Hayter <mark.hayter@gmail.com>
Date: Thu Jan 10 09:41:20 2019 +0000
- [util][pystyle] Clean python style in single file tools
+ [util][pystyle] Clean Python style in single file tools
Result of lintpy.py --fix on the diff and build_docs tools
@@ -374,14 +374,14 @@
`master` on both `origin` and `upstream` so everything is in sync at
master).
-At this point the conflicts have been cleared and the local repo can
+At this point the conflicts have been cleared and the local repository can
be used as expected.
You may find it useful to change the default for the way git reports conflicts in a file. See [Take the pain out of git conflict resolution: use diff3](https://blog.nilbus.com/take-the-pain-out-of-git-conflict-resolution-use-diff3/)
## Downloading a pull request to our local repo
-With the commands below, you can checkout a pull request from the upstream repo to
+With the commands below, you can checkout a pull request from the upstream repository to
your local repo.
```console
@@ -456,7 +456,7 @@
$ git commit -m "Add CFG examples to UART specification"
```
-* Step 3: Create your github branch for the pull request
+* Step 3: Create your GitHub branch for the pull request
```console
$ git push -u origin {BRANCH_NAME}:<remote_branch_name>
diff --git a/doc/ug/quickstart.md b/doc/ug/quickstart.md
index fa84544..69d8c81 100644
--- a/doc/ug/quickstart.md
+++ b/doc/ug/quickstart.md
@@ -20,7 +20,7 @@
## Extract the release
-Download a release bitstream from the [OpenTitan Github Releases page](https://github.com/lowRISC/opentitan/releases) and extract it.
+Download a release bitstream from the [OpenTitan GitHub Releases page](https://github.com/lowRISC/opentitan/releases) and extract it.
`$OT_TOP` refers to the location where it is extracted.
```console
diff --git a/hw/formal/README.md b/hw/formal/README.md
index b773c66..62509b0 100644
--- a/hw/formal/README.md
+++ b/hw/formal/README.md
@@ -88,14 +88,14 @@
### More Macros and Examples
* For more macros see file [prim_assert.sv](prim_assert.sv).
-* For more examples, search the repo for ASSERT by typing `grep -r ASSERT .`
+* For more examples, search the repository for ASSERT by typing `grep -r ASSERT .`
* Also see
[tlul_assert.sv](https://github.com/lowRISC/opentitan/blob/master/hw/ip/tlul/rtl/tlul_assert.sv)
and its
[documentation]({{< relref "hw/ip/tlul/doc/TlulProtocolChecker.md" >}}).
## Useful SVA System Functions
-Below table lists useful SVA (system verilog assertion) functions that can be
+Below table lists useful SVA (SystemVerilog assertion) functions that can be
used for assertion properties.
<table>
diff --git a/hw/ip/alert_handler/data/alert_handler.hjson b/hw/ip/alert_handler/data/alert_handler.hjson
index 18f0b1f..1f264af 100644
--- a/hw/ip/alert_handler/data/alert_handler.hjson
+++ b/hw/ip/alert_handler/data/alert_handler.hjson
@@ -4,7 +4,7 @@
//
# ALERT_HANDLER register template
#
-# Parameter (given by python tool)
+# Parameter (given by Python tool)
# - n_alerts: Number of alert sources
# - esc_cnt_dw: Width of escalation counter
# - accu_cnt_dw: Width of accumulator
diff --git a/hw/ip/alert_handler/data/alert_handler.hjson.tpl b/hw/ip/alert_handler/data/alert_handler.hjson.tpl
index 246cb26..9bf8c7b 100644
--- a/hw/ip/alert_handler/data/alert_handler.hjson.tpl
+++ b/hw/ip/alert_handler/data/alert_handler.hjson.tpl
@@ -4,7 +4,7 @@
//
# ALERT_HANDLER register template
#
-# Parameter (given by python tool)
+# Parameter (given by Python tool)
# - n_alerts: Number of alert sources
# - esc_cnt_dw: Width of escalation counter
# - accu_cnt_dw: Width of accumulator
diff --git a/hw/ip/alert_handler/util/reg_alert_handler.py b/hw/ip/alert_handler/util/reg_alert_handler.py
index c550d1b..1419839 100755
--- a/hw/ip/alert_handler/util/reg_alert_handler.py
+++ b/hw/ip/alert_handler/util/reg_alert_handler.py
@@ -2,7 +2,7 @@
# Copyright lowRISC contributors.
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
-r"""Convert mako template to hjson register description
+r"""Convert mako template to Hjson register description
"""
import argparse
import sys
diff --git a/hw/ip/hmac/model/hmac_model.py b/hw/ip/hmac/model/hmac_model.py
index 6565476..135ff33 100755
--- a/hw/ip/hmac/model/hmac_model.py
+++ b/hw/ip/hmac/model/hmac_model.py
@@ -2,7 +2,7 @@
# Copyright lowRISC contributors.
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
-"""HMAC-SHA256 python implementation
+"""HMAC-SHA256 Python implementation
"""
import argparse
diff --git a/hw/ip/padctrl/data/padctrl.hjson b/hw/ip/padctrl/data/padctrl.hjson
index d96e0fb..4c48f4d 100644
--- a/hw/ip/padctrl/data/padctrl.hjson
+++ b/hw/ip/padctrl/data/padctrl.hjson
@@ -4,7 +4,7 @@
//
# PADCTRL register template
#
-# Parameter (given by python tool)
+# Parameter (given by Python tool)
# - n_dio_pads: Number of dedicated IO pads
# - n_mio_pads: Number of muxed IO pads
# - attr_dw: Attribute datawidth
diff --git a/hw/ip/padctrl/data/padctrl.hjson.tpl b/hw/ip/padctrl/data/padctrl.hjson.tpl
index 0f67aa5..4546052 100644
--- a/hw/ip/padctrl/data/padctrl.hjson.tpl
+++ b/hw/ip/padctrl/data/padctrl.hjson.tpl
@@ -4,7 +4,7 @@
//
# PADCTRL register template
#
-# Parameter (given by python tool)
+# Parameter (given by Python tool)
# - n_dio_pads: Number of dedicated IO pads
# - n_mio_pads: Number of muxed IO pads
# - attr_dw: Attribute datawidth
diff --git a/hw/ip/padctrl/util/reg_padctrl.py b/hw/ip/padctrl/util/reg_padctrl.py
index 050cf26..cfeac86 100755
--- a/hw/ip/padctrl/util/reg_padctrl.py
+++ b/hw/ip/padctrl/util/reg_padctrl.py
@@ -2,7 +2,7 @@
# Copyright lowRISC contributors.
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
-r"""Convert mako template to hjson register description
+r"""Convert mako template to Hjson register description
"""
import argparse
import sys
diff --git a/hw/ip/pinmux/data/pinmux.hjson b/hw/ip/pinmux/data/pinmux.hjson
index c190b6f..0f7edb3 100644
--- a/hw/ip/pinmux/data/pinmux.hjson
+++ b/hw/ip/pinmux/data/pinmux.hjson
@@ -4,7 +4,7 @@
//
# PINMUX register template
#
-# Parameter (given by python tool)
+# Parameter (given by Python tool)
# - n_periph_in: Number of peripheral inputs
# - n_periph_out: Number of peripheral outputs
# - n_mio_pads: Number of muxed IO pads
diff --git a/hw/ip/pinmux/data/pinmux.hjson.tpl b/hw/ip/pinmux/data/pinmux.hjson.tpl
index fb774fe..c8fca75 100644
--- a/hw/ip/pinmux/data/pinmux.hjson.tpl
+++ b/hw/ip/pinmux/data/pinmux.hjson.tpl
@@ -4,7 +4,7 @@
//
# PINMUX register template
#
-# Parameter (given by python tool)
+# Parameter (given by Python tool)
# - n_periph_in: Number of peripheral inputs
# - n_periph_out: Number of peripheral outputs
# - n_mio_pads: Number of muxed IO pads
diff --git a/hw/ip/pinmux/util/reg_pinmux.py b/hw/ip/pinmux/util/reg_pinmux.py
index 2a67763..856d9be 100755
--- a/hw/ip/pinmux/util/reg_pinmux.py
+++ b/hw/ip/pinmux/util/reg_pinmux.py
@@ -2,7 +2,7 @@
# Copyright lowRISC contributors.
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
-r"""Convert mako template to hjson register description
+r"""Convert mako template to Hjson register description
"""
import argparse
import sys
diff --git a/hw/ip/prim/rtl/prim_arbiter.sv b/hw/ip/prim/rtl/prim_arbiter.sv
index ae1aea5..21d106d 100644
--- a/hw/ip/prim/rtl/prim_arbiter.sv
+++ b/hw/ip/prim/rtl/prim_arbiter.sv
@@ -4,7 +4,7 @@
//
// N:1 arbiter module
//
-// verilog parameter
+// Verilog parameter
// N: Number of request ports
// DW: Data width
//
diff --git a/hw/ip/rv_plic/README.md b/hw/ip/rv_plic/README.md
index 4ce66d5..72f81ba 100644
--- a/hw/ip/rv_plic/README.md
+++ b/hw/ip/rv_plic/README.md
@@ -7,7 +7,7 @@
## `reg_rv_plic.py`
-The tool is to create register hjson and top module `rv_plic.sv` files given
+The tool is to create register Hjson and top module `rv_plic.sv` files given
values of number of sources, number of targets, and max value of priority. By
default `sources` is **32**, `target` is **1** and `priority` is **7** (8 level of priorities
supported)
diff --git a/hw/ip/rv_plic/data/rv_plic.hjson b/hw/ip/rv_plic/data/rv_plic.hjson
index e8c12cd..c61da3b 100644
--- a/hw/ip/rv_plic/data/rv_plic.hjson
+++ b/hw/ip/rv_plic/data/rv_plic.hjson
@@ -4,7 +4,7 @@
//
# RV_PLIC register template
#
-# Parameter (given by python tool)
+# Parameter (given by Python tool)
# - src: Number of Interrupt Sources
# - target: Number of Targets that handle interrupt requests
# - prio: Max value of interrupt priorities
diff --git a/hw/ip/rv_plic/data/rv_plic.hjson.tpl b/hw/ip/rv_plic/data/rv_plic.hjson.tpl
index d926cb7..672b2ed 100644
--- a/hw/ip/rv_plic/data/rv_plic.hjson.tpl
+++ b/hw/ip/rv_plic/data/rv_plic.hjson.tpl
@@ -5,7 +5,7 @@
<% import math %>\
# RV_PLIC register template
#
-# Parameter (given by python tool)
+# Parameter (given by Python tool)
# - src: Number of Interrupt Sources
# - target: Number of Targets that handle interrupt requests
# - prio: Max value of interrupt priorities
diff --git a/hw/ip/rv_plic/data/rv_plic.sv.tpl b/hw/ip/rv_plic/data/rv_plic.sv.tpl
index de46dd4..b6c56a3 100644
--- a/hw/ip/rv_plic/data/rv_plic.sv.tpl
+++ b/hw/ip/rv_plic/data/rv_plic.sv.tpl
@@ -11,7 +11,7 @@
// Consider to set MAX_PRIO as small number as possible. It is main factor
// of area increase if edge-triggered counter isn't implemented.
//
-// verilog parameter
+// Verilog parameter
// MAX_PRIO: Maximum value of interrupt priority
module rv_plic import rv_plic_reg_pkg::*; #(
diff --git a/hw/ip/rv_plic/rtl/rv_plic.sv b/hw/ip/rv_plic/rtl/rv_plic.sv
index 84b1cd5..f494068 100644
--- a/hw/ip/rv_plic/rtl/rv_plic.sv
+++ b/hw/ip/rv_plic/rtl/rv_plic.sv
@@ -11,7 +11,7 @@
// Consider to set MAX_PRIO as small number as possible. It is main factor
// of area increase if edge-triggered counter isn't implemented.
//
-// verilog parameter
+// Verilog parameter
// MAX_PRIO: Maximum value of interrupt priority
module rv_plic import rv_plic_reg_pkg::*; #(
diff --git a/hw/ip/rv_plic/util/reg_rv_plic.py b/hw/ip/rv_plic/util/reg_rv_plic.py
index 81c3038..3b033f7 100755
--- a/hw/ip/rv_plic/util/reg_rv_plic.py
+++ b/hw/ip/rv_plic/util/reg_rv_plic.py
@@ -2,7 +2,7 @@
# Copyright lowRISC contributors.
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
-r"""Mako template to hjson register description
+r"""Mako template to Hjson register description
"""
import sys
import argparse
diff --git a/hw/ip/rv_timer/util/reg_timer.py b/hw/ip/rv_timer/util/reg_timer.py
index c9ab05c..4209060 100755
--- a/hw/ip/rv_timer/util/reg_timer.py
+++ b/hw/ip/rv_timer/util/reg_timer.py
@@ -2,7 +2,7 @@
# Copyright lowRISC contributors.
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
-r"""Mako template to hjson register description
+r"""Mako template to Hjson register description
"""
import sys
import argparse
diff --git a/hw/ip/tlul/rtl/tlul_socket_1n.sv b/hw/ip/tlul/rtl/tlul_socket_1n.sv
index e57b549..26c30fc 100644
--- a/hw/ip/tlul/rtl/tlul_socket_1n.sv
+++ b/hw/ip/tlul/rtl/tlul_socket_1n.sv
@@ -7,7 +7,7 @@
// configuration settings
// device_count: 4
//
-// verilog parameters
+// Verilog parameters
// HReqPass: if 1 then host requests can pass through on empty fifo,
// default 1
// HRspPass: if 1 then host responses can pass through on empty fifo,
diff --git a/hw/ip/tlul/rtl/tlul_socket_m1.sv b/hw/ip/tlul/rtl/tlul_socket_m1.sv
index 62e527d..b4b1b4e 100644
--- a/hw/ip/tlul/rtl/tlul_socket_m1.sv
+++ b/hw/ip/tlul/rtl/tlul_socket_m1.sv
@@ -4,7 +4,7 @@
//
// TL-UL socket M:1 module
//
-// verilog parameters
+// Verilog parameters
// M: Number of host ports.
// HReqPass: M bit array to allow requests to pass through the host i
// FIFO with no clock delay if the request FIFO is empty. If
diff --git a/hw/top_earlgrey/README.md b/hw/top_earlgrey/README.md
index 06a5929..bf15e16 100644
--- a/hw/top_earlgrey/README.md
+++ b/hw/top_earlgrey/README.md
@@ -5,7 +5,7 @@
Top Earlgrey is being generated by the integration tool, topgen
(`util/topgen.py`). Please do not revise `rtl/top_earlgrey.sv`, the crossbar
modules, and the interrupt controller directly. Those files are auto-generated
-and sit in the repo for browsing purpose.
+and sit in the repository for browsing purpose.
### How to create top module
diff --git a/hw/top_earlgrey/ip/pinmux/data/autogen/pinmux.hjson b/hw/top_earlgrey/ip/pinmux/data/autogen/pinmux.hjson
index 294c343..62e7aac 100644
--- a/hw/top_earlgrey/ip/pinmux/data/autogen/pinmux.hjson
+++ b/hw/top_earlgrey/ip/pinmux/data/autogen/pinmux.hjson
@@ -12,7 +12,7 @@
//
# PINMUX register template
#
-# Parameter (given by python tool)
+# Parameter (given by Python tool)
# - n_periph_in: Number of peripheral inputs
# - n_periph_out: Number of peripheral outputs
# - n_mio_pads: Number of muxed IO pads
diff --git a/hw/top_earlgrey/ip/rv_plic/data/autogen/rv_plic.hjson b/hw/top_earlgrey/ip/rv_plic/data/autogen/rv_plic.hjson
index ecff0c0..b9d16ba 100644
--- a/hw/top_earlgrey/ip/rv_plic/data/autogen/rv_plic.hjson
+++ b/hw/top_earlgrey/ip/rv_plic/data/autogen/rv_plic.hjson
@@ -12,7 +12,7 @@
//
# RV_PLIC register template
#
-# Parameter (given by python tool)
+# Parameter (given by Python tool)
# - src: Number of Interrupt Sources
# - target: Number of Targets that handle interrupt requests
# - prio: Max value of interrupt priorities
diff --git a/hw/top_earlgrey/ip/rv_plic/rtl/autogen/rv_plic.sv b/hw/top_earlgrey/ip/rv_plic/rtl/autogen/rv_plic.sv
index 14b3c02..aae343c 100644
--- a/hw/top_earlgrey/ip/rv_plic/rtl/autogen/rv_plic.sv
+++ b/hw/top_earlgrey/ip/rv_plic/rtl/autogen/rv_plic.sv
@@ -19,7 +19,7 @@
// Consider to set MAX_PRIO as small number as possible. It is main factor
// of area increase if edge-triggered counter isn't implemented.
//
-// verilog parameter
+// Verilog parameter
// MAX_PRIO: Maximum value of interrupt priority
module rv_plic import rv_plic_reg_pkg::*; #(
diff --git a/hw/vendor/lowrisc_ibex/vendor/google_riscv-dv/README.md b/hw/vendor/lowrisc_ibex/vendor/google_riscv-dv/README.md
index 1f35d61..c3d60d7 100644
--- a/hw/vendor/lowrisc_ibex/vendor/google_riscv-dv/README.md
+++ b/hw/vendor/lowrisc_ibex/vendor/google_riscv-dv/README.md
@@ -386,7 +386,7 @@
We have collaborated with LowRISC to apply this flow for [IBEX RISC-V core
verification](https://github.com/lowRISC/ibex/blob/master/doc/verification.rst). You can use
it as a reference to setup end-to-end co-simulation flow.
-This repo is still under active development, here's recommended approach to
+This repository is still under active development, here's recommended approach to
customize the instruction generator while keeping the minimum effort of merging
upstream changes.
- Do not modify the upstream classes directly. When possible, extend from
diff --git a/hw/vendor/lowrisc_ibex/vendor/google_riscv-dv/run.py b/hw/vendor/lowrisc_ibex/vendor/google_riscv-dv/run.py
index b2bbc71..d722880 100644
--- a/hw/vendor/lowrisc_ibex/vendor/google_riscv-dv/run.py
+++ b/hw/vendor/lowrisc_ibex/vendor/google_riscv-dv/run.py
@@ -189,7 +189,7 @@
logging.info("Generating %d %s" % (iterations, test['test']))
if iterations > 0:
"""
- If we are running a CSR test, need to call a separate python script
+ If we are running a CSR test, need to call a separate Python script
to generate directed CSR test code, located at scripts/gen_csr_test.py.
"""
if test['test'] == 'riscv_csr_test':
diff --git a/hw/vendor/pulp_riscv_dbg/debug_rom/gen_rom.py b/hw/vendor/pulp_riscv_dbg/debug_rom/gen_rom.py
index 338abbb..7577db0 100755
--- a/hw/vendor/pulp_riscv_dbg/debug_rom/gen_rom.py
+++ b/hw/vendor/pulp_riscv_dbg/debug_rom/gen_rom.py
@@ -7,7 +7,7 @@
import binascii
-parser = argparse.ArgumentParser(description='Convert binary file to verilog rom')
+parser = argparse.ArgumentParser(description='Convert binary file to Verilog rom')
parser.add_argument('filename', metavar='filename', nargs=1,
help='filename of input binary')
diff --git a/sw/device/tests/index.md b/sw/device/tests/index.md
index d7cb98f..fd22baf 100644
--- a/sw/device/tests/index.md
+++ b/sw/device/tests/index.md
@@ -10,7 +10,7 @@
To enable this cross-platform testing, each test is self-contained and do not require additional host or backend resources to verify correct behavior.
This suggests that any testing that would involve emulation of host capability, such as an external SPI host or an external host to encrypt/decrypt data, is not appropriate for these types of self-contained tests.
It is assumed those tests will live in a different directory as the host emulation will be different for each verification target.
-For FPGA / silicon this may be a host machine, while for UVM / Verilator this may be some kind of system verilog back-end.
+For FPGA / silicon this may be a host machine, while for UVM / Verilator this may be some kind of SystemVerilog back-end.
## Self Checking Mechanism
diff --git a/util/container/Dockerfile b/util/container/Dockerfile
index 7472813..eabee52 100644
--- a/util/container/Dockerfile
+++ b/util/container/Dockerfile
@@ -83,7 +83,7 @@
srecord \
zlib1g-dev
-# Install Python3 and support libraries. Cleanup install in place to reduce
+# Install Python 3 and support libraries. Cleanup install in place to reduce
# binary size.
RUN apt-get install -y \
python3 \
@@ -91,7 +91,7 @@
python3-setuptools && \
apt-get clean; rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/*
-# Copy repo into tmp directory to execute additional install steps.
+# Copy repository into tmp directory to execute additional install steps.
COPY python-requirements.txt /tmp/python-requirements.txt
RUN pip3 install -r /tmp/python-requirements.txt
diff --git a/util/container/README.md b/util/container/README.md
index 9a0b958..ed4afa0 100644
--- a/util/container/README.md
+++ b/util/container/README.md
@@ -3,7 +3,7 @@
Docker container based on Ubuntu 16.04 LTS containing various hardware and
software development tools for OpenTitan. Current list of tools:
-* Python3
+* Python 3
* fusesoc
* OpenOCD
* RISCV toolchain
diff --git a/util/dashboard/dashboard_validate.py b/util/dashboard/dashboard_validate.py
index e323651..dd1a05d 100644
--- a/util/dashboard/dashboard_validate.py
+++ b/util/dashboard/dashboard_validate.py
@@ -2,7 +2,7 @@
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
"""
-Dashboard project json file validation
+Dashboard project JSON file validation
"""
import logging as log
diff --git a/util/dashboard/gen_dashboard_entry.py b/util/dashboard/gen_dashboard_entry.py
index fd4e1da..0a293ba 100644
--- a/util/dashboard/gen_dashboard_entry.py
+++ b/util/dashboard/gen_dashboard_entry.py
@@ -2,7 +2,7 @@
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
"""
-Generate html documentation from validated dashboard json tree
+Generate HTML documentation from validated dashboard Hjson tree
"""
import sys
diff --git a/util/reggen/README.md b/util/reggen/README.md
index 4b798e7..94a84d2 100644
--- a/util/reggen/README.md
+++ b/util/reggen/README.md
@@ -2,9 +2,9 @@
The utility script `regtool.py` and collateral under `reggen` are Python
tools to read register descriptions in Hjson and generate various output
-formats. The tool can output html documentation, standard json, compact
-standard json (whitespace removed) and Hjson. The example commands assume
-`$REPO_TOP` is set to the toplevel directory of the repo.
+formats. The tool can output HTML documentation, standard JSON, compact
+standard JSON (whitespace removed) and Hjson. The example commands assume
+`$REPO_TOP` is set to the toplevel directory of the repository.
### Setup
@@ -19,9 +19,9 @@
### Register JSON Format
-To ensure things stay up to date, the register json format information
+To ensure things stay up to date, the register JSON format information
is documented by the tool itself. Documentation can be generated by
-running the tool to produce markdown and processing that into html.
+running the tool to produce Markdown and processing that into HTML.
This information can also be found in the
[register tool documentation](../../doc/rm/register_tool.md).
This references features in the [docgen](../docgen/README.md) suite
@@ -40,8 +40,8 @@
The script `regtool.py` provides a standalone way to run `reggen`.
Note that the same example inputs are used here as for `docgen`.
-This generates html from the register description and is verbose. Since
-embeddable html is generated, the css is not included, so the output will
+This generates HTML from the register description and is verbose. Since
+embeddable HTML is generated, the CSS is not included, so the output will
not be perfectly formatted.
```console
@@ -50,7 +50,7 @@
```
The following shows an example of how to generate the full featured
-standard json from the register description Hjson file:
+standard JSON from the register description Hjson file:
```console
$ cd $REPO_TOP/util
diff --git a/util/reggen/gen_cfg_html.py b/util/reggen/gen_cfg_html.py
index 7d07102..5170dab 100644
--- a/util/reggen/gen_cfg_html.py
+++ b/util/reggen/gen_cfg_html.py
@@ -2,7 +2,7 @@
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
"""
-Generate html documentation from validated configuration json tree
+Generate HTML documentation from validated configuration Hjson tree
"""
import sys
diff --git a/util/reggen/gen_cheader.py b/util/reggen/gen_cheader.py
index 7f8836d..6d242cb 100644
--- a/util/reggen/gen_cheader.py
+++ b/util/reggen/gen_cheader.py
@@ -2,7 +2,7 @@
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
"""
-Generate C header from validated register json tree
+Generate C header from validated register JSON tree
"""
import io
diff --git a/util/reggen/gen_ctheader.py b/util/reggen/gen_ctheader.py
index 3fa1594..a433e2d 100644
--- a/util/reggen/gen_ctheader.py
+++ b/util/reggen/gen_ctheader.py
@@ -2,7 +2,7 @@
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
"""
-Generate C header (Titan style) from validated register json tree
+Generate C header (Titan style) from validated register JSON tree
"""
import io
diff --git a/util/reggen/gen_dv.py b/util/reggen/gen_dv.py
index 20d7ed1..ac0e225 100644
--- a/util/reggen/gen_dv.py
+++ b/util/reggen/gen_dv.py
@@ -1,7 +1,7 @@
# Copyright lowRISC contributors.
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
-"""Generate SystemVerilog designs from validated register json tree
+"""Generate SystemVerilog designs from validated register JSON tree
"""
import logging as log
diff --git a/util/reggen/gen_html.py b/util/reggen/gen_html.py
index d888532..a4c6116 100644
--- a/util/reggen/gen_html.py
+++ b/util/reggen/gen_html.py
@@ -2,7 +2,7 @@
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
"""
-Generate html documentation from validated register json tree
+Generate HTML documentation from validated register Hjson tree
"""
import logging as log
@@ -14,7 +14,7 @@
outfile.write(msg)
-# expand !!register references into html links, gen **bold** and *italic*
+# expand !!register references into HTML links, gen **bold** and *italic*
def desc_expand(s, rnames):
def fieldsub(match):
base = match.group(1).partition('.')[0].lower()
diff --git a/util/reggen/gen_json.py b/util/reggen/gen_json.py
index 7088d17..ffab523 100644
--- a/util/reggen/gen_json.py
+++ b/util/reggen/gen_json.py
@@ -2,7 +2,7 @@
# Copyright lowRISC contributors.
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
-"""Generate json/compact json/hjson from register json tree
+"""Generate JSON/compact JSON/Hjson from register JSON tree
"""
import hjson
@@ -29,4 +29,4 @@
hjson.dump(
obj, outfile, ensure_ascii=False, for_json=True, use_decimal=True)
else:
- raise ValueError('Invalid json format ' + format)
+ raise ValueError('Invalid JSON format ' + format)
diff --git a/util/reggen/gen_rtl.py b/util/reggen/gen_rtl.py
index 9161192..5e762a7 100644
--- a/util/reggen/gen_rtl.py
+++ b/util/reggen/gen_rtl.py
@@ -1,7 +1,7 @@
# Copyright lowRISC contributors.
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
-"""Generate SystemVerilog designs from validated register json tree
+"""Generate SystemVerilog designs from validated register JSON tree
"""
import logging as log
@@ -122,7 +122,7 @@
def json_to_reg(obj):
- """Converts json OrderedDict into structure having useful information for
+ """Converts JSON OrderedDict into structure having useful information for
Template to use.
Main purpose of this function is:
diff --git a/util/reggen/gen_selfdoc.py b/util/reggen/gen_selfdoc.py
index 49dd7df..7d80402 100644
--- a/util/reggen/gen_selfdoc.py
+++ b/util/reggen/gen_selfdoc.py
@@ -89,7 +89,7 @@
Field names should be relatively short because they will be used
frequently (and need to fit in the register layout picture!) The field
description is expected to be longer and will most likely make use of
-the hjson ability to include multi-line strings. An example with three
+the Hjson ability to include multi-line strings. An example with three
fields:
```hjson
@@ -234,7 +234,7 @@
doc_tbl_line(outfile, x, None, validate.hwaccess_permitted[x][0])
genout(outfile,
- "\n\nThe top level of the json is a group containing "\
+ "\n\nThe top level of the JSON is a group containing "\
"the following keys:\n")
doc_tbl_head(outfile, 1)
for x in validate.top_required:
diff --git a/util/reggen/reg_html.css b/util/reggen/reg_html.css
index 9beaf15..c657573 100644
--- a/util/reggen/reg_html.css
+++ b/util/reggen/reg_html.css
@@ -1,4 +1,4 @@
-/* Stylesheet for reggen html register output */
+/* Stylesheet for reggen HTML register output */
/* Copyright lowRISC contributors. */
/* Licensed under the Apache License, Version 2.0, see LICENSE for details.*/
/* SPDX-License-Identifier: Apache-2.0 */
diff --git a/util/reggen/validate.py b/util/reggen/validate.py
index 89fed02..4ffbaf4 100644
--- a/util/reggen/validate.py
+++ b/util/reggen/validate.py
@@ -2,7 +2,7 @@
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
"""
-Register json validation
+Register JSON validation
"""
import logging as log
@@ -11,7 +11,7 @@
from reggen.field_enums import *
-# Routine that can be used for hjson object_pairs_hook
+# Routine that can be used for Hjson object_pairs_hook
# The baseline is dict(pairs) i.e. construct a dictonary from pairs
# The usual is OrderedDict(pairs) which is redundant in latest python
# Both of these silently allow repeated keys, which this version detects
@@ -277,10 +277,10 @@
't': ["text", "string, may be multi-line enclosed in `'''` "\
"may use `**bold**`, `*italic*` or `!!Reg` markup"],
'T': ["tuple", "tuple enclosed in ()"],
- 'pi': ["python int", "Native python type int (generated)"],
- 'pb': ["python Bool", "Native python type Bool (generated)"],
- 'pl': ["python list", "Native python type list (generated)"],
- 'pe': ["python enum", "Native python type enum (generated)"]
+ 'pi': ["python int", "Native Python type int (generated)"],
+ 'pb': ["python Bool", "Native Python type Bool (generated)"],
+ 'pl': ["python list", "Native Python type list (generated)"],
+ 'pe': ["python enum", "Native Python type enum (generated)"]
}
# Toplevel keys
@@ -603,7 +603,7 @@
fname = field['name']
if fname in keywords_verilog:
error += 1
- log.error(rname + " field " + fname + " uses verilog keywords")
+ log.error(rname + " field " + fname + " uses Verilog keywords")
if (fname == ""):
fname = rname + ".field" + str(fcount)
else:
@@ -855,7 +855,7 @@
if rname in keywords_verilog:
error += 1
log.error("Register at +" + hex(offset) + rname +
- " uses verilog keywords")
+ " uses Verilog keywords")
if rname.lower() in top['genrnames']:
error += 1
log.error("Register at +" + hex(offset) + " duplicate name " +
diff --git a/util/regtool.py b/util/regtool.py
index e96da59..9040cff 100755
--- a/util/regtool.py
+++ b/util/regtool.py
@@ -18,7 +18,7 @@
from reggen import (gen_cheader, gen_ctheader, gen_dv, gen_html, gen_json,
gen_rtl, gen_selfdoc, validate, version)
-DESC = """regtool, generate register info from hjson source"""
+DESC = """regtool, generate register info from Hjson source"""
USAGE = '''
regtool [options]
@@ -42,7 +42,7 @@
metavar='file',
type=argparse.FileType('r'),
default=sys.stdin,
- help='input file in hjson type')
+ help='input file in Hjson type')
parser.add_argument('-d',
action='store_true',
help='Output register documentation (html)')
diff --git a/util/syn_yosys.sh b/util/syn_yosys.sh
index 2eabed4..4bebe42 100755
--- a/util/syn_yosys.sh
+++ b/util/syn_yosys.sh
@@ -45,7 +45,7 @@
\rm -Rf *_pkg.v
#-------------------------------------------------------------------------
-# run LEC (generarted verilog vs. original SystemVerilog)
+# run LEC (generarted Verilog vs. original SystemVerilog)
#-------------------------------------------------------------------------
printf "\n\nLEC RESULTS:\n"
cd ../../hw/formal
@@ -69,7 +69,7 @@
#-------------------------------------------------------------------------
printf "\n\nYosys:\n"
-# for now, read in each verilog file into Yosys and only output errors
+# for now, read in each Verilog file into Yosys and only output errors
# and warnings
for file in *.v; do
yosys -QTqp "read_verilog ${file}"
diff --git a/util/testplanner.py b/util/testplanner.py
index 9144eaa..b93eaf5 100755
--- a/util/testplanner.py
+++ b/util/testplanner.py
@@ -2,7 +2,7 @@
# Copyright lowRISC contributors.
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
-r"""Command-line tool to parse and process testplan hjson
+r"""Command-line tool to parse and process testplan Hjson
"""
import argparse
@@ -23,18 +23,18 @@
parser.add_argument(
'testplan',
metavar='<hjson-file>',
- help='input testplan file in hjson')
+ help='input testplan file (*.hjson)')
parser.add_argument(
'-r',
'--regr_results',
metavar='<hjson-file>',
- help='input regression results file in hjson')
+ help='input regression results file (*.hjson)')
parser.add_argument(
'--outfile',
'-o',
type=argparse.FileType('w'),
default=sys.stdout,
- help='output html file (without css)')
+ help='output HTML file (without CSS)')
args = parser.parse_args()
outfile = args.outfile
diff --git a/util/testplanner/README.md b/util/testplanner/README.md
index 1c32b96..0e5c713 100644
--- a/util/testplanner/README.md
+++ b/util/testplanner/README.md
@@ -37,7 +37,7 @@
that the reader gets the full picture of what and how the said feature is being
tested.
- Full [markdown]({{< relref "doc/rm/markdown_usage_style" >}}) syntax is supported
+ Full [Markdown]({{< relref "doc/rm/markdown_usage_style" >}}) syntax is supported
when writing the description.
* **tests: list of actual written tests that maps to this planned test**
diff --git a/util/testplanner/examples/foo_testplan.hjson b/util/testplanner/examples/foo_testplan.hjson
index bbb1bb8..2bdca9a 100644
--- a/util/testplanner/examples/foo_testplan.hjson
+++ b/util/testplanner/examples/foo_testplan.hjson
@@ -7,7 +7,7 @@
intf: ["", "_jtag"]
// 'import_testplans' is a list of imported common testplans
- // paths are relative to repo top
+ // paths are relative to repository top
// all key_value pairs in this file other than 'import_testplans' and 'entries'
// can be used for wildcard substitutions in imported testplans
import_testplans: ["util/testplanner/examples/common_testplan.hjson"]
@@ -40,11 +40,11 @@
this.
**Check**: This style is not mandatory, but highly recommended. Also note that
- the description supports markdown formatting. Add things:
+ the description supports Markdown formatting. Add things:
- like bullets
- something in **bold** and in *italic*
- A sub-bullet item<br>
- Continue describing above bullet on a new line with a html line break.
+ Continue describing above bullet on a new line with a HTML line break.
Start a new para with with 2 newlines.
'''
diff --git a/util/testplanner/testplan_utils.py b/util/testplanner/testplan_utils.py
index 9ecdf8e..3365b60 100644
--- a/util/testplanner/testplan_utils.py
+++ b/util/testplanner/testplan_utils.py
@@ -2,7 +2,7 @@
# Copyright lowRISC contributors.
# Licensed under the Apache License, Version 2.0, see LICENSE for details.
# SPDX-License-Identifier: Apache-2.0
-r"""Command-line tool to parse and process testplan hjson into a data structure
+r"""Command-line tool to parse and process testplan Hjson into a data structure
The data structure is used for expansion inline within DV plan documentation
as well as for annotating the regression results.
"""
@@ -18,7 +18,7 @@
def parse_testplan(filename):
- '''Parse testplan hjson file into a datastructure'''
+ '''Parse testplan Hjson file into a datastructure'''
self_path = os.path.dirname(os.path.realpath(__file__))
repo_root = os.path.abspath(os.path.join(self_path, os.pardir, os.pardir))
@@ -72,7 +72,7 @@
def gen_html_testplan_table(testplan, outbuf):
- '''generate html table from testplan with the following fields
+ '''generate HTML table from testplan with the following fields
milestone, planned test name, description
'''
def print_row(ms, name, desc, tests, cell, outbuf):
diff --git a/util/tlgen.py b/util/tlgen.py
index 507c610..3d50e56 100755
--- a/util/tlgen.py
+++ b/util/tlgen.py
@@ -27,7 +27,7 @@
parser.add_argument('--doc',
'-d',
action='store_true',
- help='Generate self html document in stdout')
+ help='Generate self HTML document in stdout')
parser.add_argument(
'--outdir',
'-o',
diff --git a/util/tlgen/doc.py b/util/tlgen/doc.py
index 1c0bf83..41cc8c0 100644
--- a/util/tlgen/doc.py
+++ b/util/tlgen/doc.py
@@ -78,7 +78,7 @@
def selfdoc(heading, cmd=""):
- # heading : markdown header depth
+ # heading : Markdown header depth
# value type
outstr = doc_intro.format(cmd)
diff --git a/util/tlgen/validate.py b/util/tlgen/validate.py
index ce232f4..096c381 100644
--- a/util/tlgen/validate.py
+++ b/util/tlgen/validate.py
@@ -30,10 +30,10 @@
# 't': ["text", "string, may be multi-line enclosed in `'''` "\
# "may use `**bold**`, `*italic*` or `!!Reg` markup"],
# 'T': ["tuple", "tuple enclosed in ()"],
-# 'pi': ["python int", "Native python type int (generated)"],
-# 'pb': ["python Bool", "Native python type Bool (generated)"],
-# 'pl': ["python list", "Native python type list (generated)"],
-# 'pe': ["python enum", "Native python type enum (generated)"]
+# 'pi': ["python int", "Native Python type int (generated)"],
+# 'pb': ["python Bool", "Native Python type Bool (generated)"],
+# 'pl': ["python list", "Native Python type list (generated)"],
+# 'pe': ["python enum", "Native Python type enum (generated)"]
# }
node = {
'name': 'Node configuration',
@@ -70,7 +70,7 @@
'nodes': ['lg', node]
},
'optional': {
- 'type': ['s', 'Indicate hjson type. "xbar" always if exist']
+ 'type': ['s', 'Indicate Hjson type. "xbar" always if exist']
},
'added': {
'reset_connections': ['g', "Generated by topgen. Key is the reset signal inside IP"\
@@ -188,7 +188,7 @@
addr_ranges = []
- obj, err = validate_hjson(obj) # validate hjson format first
+ obj, err = validate_hjson(obj) # validate Hjson format first
if err > 0:
log.error("Hjson structure error")
return
diff --git a/util/topgen.py b/util/topgen.py
index ae4b2fb..a60f983 100755
--- a/util/topgen.py
+++ b/util/topgen.py
@@ -310,11 +310,11 @@
parser.add_argument(
'--plic-only',
action='store_true',
- help="If defined, the tool generates RV_PLIC RTL and hjson only")
+ help="If defined, the tool generates RV_PLIC RTL and Hjson only")
parser.add_argument(
'--hjson-only',
action='store_true',
- help="If defined, the tool generates complete hjson only")
+ help="If defined, the tool generates complete Hjson only")
# Generator options: generate dv ral model
parser.add_argument(
'--top_ral',
@@ -387,7 +387,7 @@
pinmux_hjson = hjson_dir.parent / 'ip/pinmux/data/autogen/pinmux.hjson'
ips.append(pinmux_hjson)
- # load hjson and pass validate from reggen
+ # load Hjson and pass validate from reggen
try:
ip_objs = []
for x in ips:
diff --git a/util/topgen/lib.py b/util/topgen/lib.py
index 7f60c08..fa1f8de 100644
--- a/util/topgen/lib.py
+++ b/util/topgen/lib.py
@@ -23,7 +23,7 @@
def search_ips(ip_path): # return list of config files
- # list the every hjson file
+ # list the every Hjson file
p = ip_path.glob('*/data/*.hjson')
# filter only ip_name/data/ip_name{_reg|''}.hjson
@@ -41,9 +41,9 @@
def get_hjsonobj_xbars(xbar_path):
- """ Search crossbars hjson files from given path.
+ """ Search crossbars Hjson files from given path.
- Search every hjson in the directory and check hjson type.
+ Search every Hjson in the directory and check Hjson type.
It could be type: "top" or type: "xbar"
returns [(name, obj), ... ]
"""
diff --git a/util/topgen/merge.py b/util/topgen/merge.py
index bad184f..86c91b5 100644
--- a/util/topgen/merge.py
+++ b/util/topgen/merge.py
@@ -99,7 +99,7 @@
ip_module["scan"] = "false"
-# TODO: Replace this part to be configurable from hjson or template
+# TODO: Replace this part to be configurable from Hjson or template
predefined_modules = {
"corei": "rv_core_ibex",
"cored": "rv_core_ibex",
diff --git a/util/topgen/validate.py b/util/topgen/validate.py
index d875163..6c13472 100644
--- a/util/topgen/validate.py
+++ b/util/topgen/validate.py
@@ -25,10 +25,10 @@
# 't': ["text", "string, may be multi-line enclosed in `'''` "\
# "may use `**bold**`, `*italic*` or `!!Reg` markup"],
# 'T': ["tuple", "tuple enclosed in ()"],
-# 'pi': ["python int", "Native python type int (generated)"],
-# 'pb': ["python Bool", "Native python type Bool (generated)"],
-# 'pl': ["python list", "Native python type list (generated)"],
-# 'pe': ["python enum", "Native python type enum (generated)"]
+# 'pi': ["python int", "Native Python type int (generated)"],
+# 'pb': ["python Bool", "Native Python type Bool (generated)"],
+# 'pl': ["python list", "Native Python type list (generated)"],
+# 'pe': ["python enum", "Native Python type enum (generated)"]
# }
# Required/optional field in top hjson
diff --git a/util/wavegen/README.md b/util/wavegen/README.md
index cd163f5..1d6057c 100644
--- a/util/wavegen/README.md
+++ b/util/wavegen/README.md
@@ -3,7 +3,7 @@
Wavegen is a Python tool to read waveform descriptions in Hjson and
generate `svg` pictures of the waveform.
-The source is a json representation of the waveform using the wavejson
+The source is a JSON representation of the waveform using the wavejson
format defined for Wavedrom. This is sort of described at
[here](https://github.com/drom/wavedrom/wiki/WaveJSON)
diff --git a/util/wavegen/wavesvg.py b/util/wavegen/wavesvg.py
index 12eadf2..060d5fb 100644
--- a/util/wavegen/wavesvg.py
+++ b/util/wavegen/wavesvg.py
@@ -637,7 +637,7 @@
return len(bricks)
-# obj is hjson parsed object with wavejson
+# obj is Hjson parsed object with wavejson
# svg_num is a number that makes this svg unique. First one must be 0
