[doc] Update references to util/vendor.py tool.
As part of lowrisc/opentitan#607, rename references from `vendor_hw` to
`util/vendor`. Also, rename `doc/rm/vendor_hw_tool.md` as
`doc/rm/vendor_in_tool.md`.
Signed-off-by: Miguel Osorio <miguelosorio@google.com>
diff --git a/doc/rm/_index.md b/doc/rm/_index.md
index e8dc25a..4deb30d 100644
--- a/doc/rm/_index.md
+++ b/doc/rm/_index.md
@@ -5,7 +5,7 @@
* [Topgen Tool]({{< relref "topgen_tool" >}}): Describes `topgen.py` and its Hjson format source. Used to generate rtl and validation files for top specific modules such as PLIC, Pinmux and crossbar.
* [Register Tool]({{< relref "register_tool" >}}): Describes `regtool.py` and its Hjson format source. Used to generate documentation, rtl, header files and validation files for IP Registers and toplevel.
* [Crossbar Tool]({{< relref "crossbar_tool" >}}): Describes `tlgen.py` and its Hjson format source. Used to generate self-documentation, rtl files of the crossbars at the toplevel.
- * [Vendor-In Tool]({{< relref "vendor_hw_tool" >}}): Describes `vendor_hw.py` and its Hjson control file. Used to pull a local copy of code maintained in other upstream repositories and apply local patch sets.
+ * [Vendor-In Tool]({{< relref "vendor_in_tool" >}}): Describes `util/vendor.py` and its Hjson control file. Used to pull a local copy of code maintained in other upstream repositories and apply local patch sets.
* Coding Style Guides
* [Verilog Coding Style](https://github.com/lowRISC/style-guides/blob/master/VerilogCodingStyle.md)
* [Python Coding Style]({{< relref "python_coding_style.md" >}})
diff --git a/doc/rm/vendor_hw_tool.md b/doc/rm/vendor_in_tool.md
similarity index 76%
rename from doc/rm/vendor_hw_tool.md
rename to doc/rm/vendor_in_tool.md
index a8b0746..d33f0fb 100644
--- a/doc/rm/vendor_hw_tool.md
+++ b/doc/rm/vendor_in_tool.md
@@ -1,19 +1,19 @@
---
-title: "vendor_hw: vendor-in hardware components"
+title: "util/vendor.py: Vendor-in Components"
---
-Not all hardware code contained in this repository is actually developed within this repository.
-Code which we include from external sources is placed in the `hw/vendor` directory and copied into this directory from its upstream source.
-The process of copying the upstream sources is called vendoring, and it is automated by the `vendor_hw` tool.
+Not all code contained in this repository is actually developed within this repository.
+Code which we include from external sources is placed in `vendor` sub-directories (e.g. `hw/vendor`) and copied over from upstream sources.
+The process of copying the upstream sources is called vendoring, and it is automated by the `util/vendor` tool.
-The `vendor_hw` tool can go beyond simply copying in source files: it can patch them, it can export patches from commits in a Git repository, and it can commit the resulting changes with a meaningful commit message.
+The `util/vendor` tool can go beyond simply copying in source files: it can patch them, it can export patches from commits in a Git repository, and it can commit the resulting changes with a meaningful commit message.
## Tool usage overview
```text
-usage: vendor_hw [-h] [--refresh-patches] [--commit] [--verbose] file
+usage: vendor [-h] [--refresh-patches] [--commit] [--verbose] file
-vendor_hw, copy hardware source code from upstream into this repository
+vendor, copy source code from upstream into this repository
positional arguments:
file vendoring description file (*.vendor.hjson)
@@ -27,8 +27,8 @@
## The vendor description file
-For each vendored-in component a description file must be created, which serves as input to the `vendor_hw` tool.
-The vendor description file is stored in `hw/vendor/<vendor>_<name>.vendor.hjson`.
+For each vendored-in component a description file must be created, which serves as input to the `util/vendor` tool.
+The vendor description file is stored in `vendor/<vendor>_<name>.vendor.hjson`.
By convention all imported code is named `<vendor>_<name>`, with `<vendor>` typically being the GitHub user or organization name, and `<name>` the project name.
It is recommended to use only lower-case characters.
@@ -61,7 +61,7 @@
patch_dir: "patches/pulp_riscv_dbg",
// Optional: Update patches in |patch_dir| from a Git repository
- // If vendor_hw is run with --refresh-patches, all commits in the repository
+ // If util/vendor is run with --refresh-patches, all commits in the repository
// at |url| between |rev_base| and |rev_patched| are exported into the
// |patch_dir|, replacing all existing patches.
patch_repo: {
@@ -105,5 +105,5 @@
### Update code and commit the new code
```command
$ cd $REPO_TOP
-$ ./util/vendor_hw.py hw/vendor/google_riscv-dv.vendor.hjson -v --commit
+$ ./util/vendor.py hw/vendor/google_riscv-dv.vendor.hjson -v --commit
```
diff --git a/doc/ug/vendor_hw.md b/doc/ug/vendor_hw.md
index f4a3aa7..fe95dda 100644
--- a/doc/ug/vendor_hw.md
+++ b/doc/ug/vendor_hw.md
@@ -18,7 +18,7 @@
They might differ from our own rules.
- Use the upstream mechanisms to do code changes. In many cases, upstream uses GitHub just like we do with Pull Requests.
- Work with upstream reviewers to get your changes merged into their code base.
-- Once the change is part of the upstream repository, the `vendor_hw` tool can be used to copy the upstream code back into our OpenTitan repository.
+- Once the change is part of the upstream repository, the `util/vendor` tool can be used to copy the upstream code back into our OpenTitan repository.
Read on for the longer version of these guidelines.
@@ -46,7 +46,7 @@
But what happens if the imported code needs to be modified?
Ideally, all code changes are submitted upstream, integrated into the upstream code base, and then re-imported into our code base.
-This development methodology is called "upstream first".
+This development methodology is called "upstream first".
History has shown repeatedly that an upstream first policy can help significantly with the long-term maintenance of code.
However, strictly following an upstream first policy isn't great either.
@@ -64,8 +64,8 @@
All imported ("vendored") hardware code is by convention put into the `hw/vendor` directory.
(We have more conventions for file and directory names which are discussed below when the import of new code is described.)
-To interact with code in this directory a tool called `vendor_hw` is used, which can be found in `util/vendor_hw.py`.
-A "vendor description file" controls the vendoring process and serves as input to the `vendor_hw` tool.
+To interact with code in this directory a tool called `util/vendor.py` is used.
+A "vendor description file" controls the vendoring process and serves as input to the `util/vendor` tool.
In the simple, yet typical, case, the vendor description file is only a couple of lines of human-readable JSON:
@@ -86,11 +86,11 @@
We vendor a component called "lowrisc_ibex" and place the code into the "lowrisc_ibex" directory (relative to the description file).
The code comes from the master branch of the Git repository found at https://github.com/lowRISC/ibex.git.
-With this description file written, the `vendor_hw` tool can do its job.
+With this description file written, the `util/vendor` tool can do its job.
```command
$ cd $REPO_TOP
-$ ./util/vendor_hw.py hw/vendor/lowrisc_ibex.vendor.hjson --verbose
+$ ./util/vendor.py hw/vendor/lowrisc_ibex.vendor.hjson --verbose
INFO: Cloning upstream repository https://github.com/lowRISC/ibex.git @ master
INFO: Cloned at revision 7728b7b6f2318fb4078945570a55af31ee77537a
INFO: Copying upstream sources to /home/philipp/src/opentitan/hw/vendor/lowrisc_ibex
@@ -100,7 +100,7 @@
INFO: Import finished
```
-Looking at the output, you might wonder: how did the `vendor_hw` tool know what changed since the last import?
+Looking at the output, you might wonder: how did the `util/vendor` tool know what changed since the last import?
It knows because it records the commit hash of the last import in a file called the "lock file".
This file can be found along the `.vendor.hjson` file, it's named `.lock.hjson`.
@@ -119,7 +119,7 @@
The lock file should be committed together with the code itself to make the import step reproducible at any time.
-After running `vendor_hw`, the code in your local working copy is updated to the latest upstream version.
+After running `util/vendor`, the code in your local working copy is updated to the latest upstream version.
Next is testing: run simulations, syntheses, or other tests to ensure that the new code works as expected.
Once you're confident that the new code is good to be committed, do so using the normal Git commands.
@@ -136,11 +136,11 @@
$ git commit
```
-Instead of running `vendor_hw` first, and then manually creating a Git commit, you can also use the `--commit` flag.
+Instead of running `util/vendor` first, and then manually creating a Git commit, you can also use the `--commit` flag.
```command
$ cd $REPO_TOP
-$ ./util/vendor_hw.py hw/vendor/lowrisc_ibex.vendor.hjson --verbose --commit
+$ ./util/vendor.py hw/vendor/lowrisc_ibex.vendor.hjson --verbose --commit
```
This command updates the "lowrisc_ibex" code, and creates a Git commit from it.
@@ -158,7 +158,7 @@
$ # Create a new branch for the pull request
$ git checkout -b update-ibex-code upstream/master
$ # Update lowrisc_ibex and create a commit
-$ ./util/vendor_hw.py hw/vendor/lowrisc_ibex.vendor.hjson --verbose --commit
+$ ./util/vendor.py hw/vendor/lowrisc_ibex.vendor.hjson --verbose --commit
$ # Push the new branch to your fork
$ git push origin update-ibex-code
$ # Restore changes in working directory (if anything was stashed before)
@@ -239,11 +239,11 @@
### Step 4: Update the vendored copy of the external dependency
-After your change is accepted upstream, you can update our copy of the code using the `vendor_hw` tool as described before.
+After your change is accepted upstream, you can update our copy of the code using the `util/vendor` tool as described before.
## How to vendor new code
-Vendoring external code is done by creating a vendor description file, and then running the `vendor_hw` tool.
+Vendoring external code is done by creating a vendor description file, and then running the `util/vendor` tool.
1. Create a vendor description file for the new dependency.
1. Make note of the Git repository and the branch you want to vendor in.
@@ -282,11 +282,11 @@
$ git commit
```
-4. Run the `vendor_hw` tool for the newly vendored code.
+4. Run the `util/vendor` tool for the newly vendored code.
```command
$ cd $REPO_TOP
- $ ./util/vendor_hw.py hw/vendor/lowrisc_ibex.vendor.hjson --verbose --commit
+ $ ./util/vendor.py hw/vendor/lowrisc_ibex.vendor.hjson --verbose --commit
```
5. Push the branch to your fork for review (assuming `origin` is the remote name of your fork).
@@ -319,7 +319,7 @@
## How to add patches on top of the imported code
In some cases the upstream code must be modified before it can be used.
-For this purpose, the `vendor_hw` tool can apply patches on top of imported code.
+For this purpose, the `util/vendor` tool can apply patches on top of imported code.
The patches are kept as separate files in our repository, making it easy to understand the differences to the upstream code, and to switch the upstream code to a newer version.
To apply patches on top of vendored code, do the following:
@@ -333,7 +333,7 @@
2. Place patch files with a `.patch` suffix in the `patch_dir`.
-3. When running `vendor_hw`, patches are applied on top of the imported code according to the following rules.
+3. When running `util/vendor`, patches are applied on top of the imported code according to the following rules.
- Patches are applied alphabetical order according to the filename.
Name patches like `0001-do-someting.patch` to apply them in a deterministic order.
@@ -354,9 +354,9 @@
- Create a forked Git repository of the upstream code
- Create a new branch in this fork.
- Commit all your changes on top of the upstream code into this branch.
-- Convert all commits into patch files and store them where the `vendor_hw` tool can find and apply them.
+- Convert all commits into patch files and store them where the `util/vendor` tool can find and apply them.
-The last step is automated by the `vendor_hw` tool through its `--refresh-patches` argument.
+The last step is automated by the `util/vendor` tool through its `--refresh-patches` argument.
1. Modify the vendor description file to add a `patch_repo` section.
- The `url` parameter specifies the URL to the fork of the upstream repository containing all modifications.
@@ -379,7 +379,7 @@
git push REMOTE_NAME_FORK master changes
```
-3. Run the `vendor_hw` tool with the `--refresh-patches` argument.
+3. Run the `util/vendor` tool with the `--refresh-patches` argument.
It will first check out the patch repository and convert all commits which are in the `rev_patched` branch and not in the `rev_base` branch into patch files.
These patch files are then stored in the patch directory.
After that, the vendoring process continues as usual: all patches are applied and if instructed by the `--commit` flag, a commit is created.
