doc/rm/vendor_hw_tool.md

{{% lowrisc-doc-hdr: vendor_hw: vendor-in hardware 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.

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.

## Tool usage overview

```text
usage: vendor_hw [-h] [--refresh-patches] [--commit] [--verbose] file

vendor_hw, copy hardware source code from upstream into this repository

positional arguments:
  file               vendoring description file (*.vendor.hjson)

optional arguments:
  -h, --help         show this help message and exit
  --refresh-patches  Refresh the patches from the patch repository
  --commit, -c       Commit the changes
  --verbose, -v      Verbose
```

## 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`.
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.

A full commented example of a vendor description file is given below.
All relative paths are relative to the description file.
Optional parts can be removed if they are not used.

```
// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{
  // Name of the vendored-in project
  name: "pulp_riscv_dbg",

  // Target directory: typically equal to the name
  // All imported code is copied into this directory
  target_dir: "pulp_riscv_dbg",

  // Git upstream source code repository
  upstream: {
    // Upstream Git repository URL. HTTPS URLs are preferred.
    url: "https://github.com/pulp-platform/riscv-dbg",
    // Upstream revision or branch. Can be a commit hash or a branch name.
    rev: "pulpissimo_integration",
  },

  // Optional: Apply patches from the following directory to the upstream
  // sources
  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
  // at |url| between |rev_base| and |rev_patched| are exported into the
  // |patch_dir|, replacing all existing patches.
  patch_repo: {
    url: "git@github.com:lowRISC/riscv-dbg.git",
    rev_base: "pulpissimo_integration",
    rev_patched: "ot",
  },

  // Optional: Exclude files or directories from the upstream sources
  // The standard glob wildcards (*, ?, etc.) are supported
  exclude_from_upstream: [
    "src/dm_top.sv",
    "src_files.yml",
  ]
}
```

## Examples

### Update code and commit the new code
```command
$ cd $REPO_TOP
$ ./util/vendor_hw.py hw/vendor/google_riscv-dv.vendor.hjson -v --commit
```