Third-party policy for Hardware Development in Google3

Policy

• Hardware teams may maintain all third_party IP required for their projects in //piper/.../hardware.
• In contrast to the standard ban on multiple versions in //third_party, each IP sub-directory in the hardware directory is permitted up to four versions.
• At least four hardware FTEs must be in //piper/.../OWNERS at all times.

Rationale

The manufacturing and deployment time for hardware projects is generally very long. To support the long development cycle, a project may need to freeze versions of their third-party IP.

Example

When a chip design is sent to a silicon foundry (commonly called “tape out”),
the exact version of all code that contributed to that design needs to be frozen
in case incremental modifications need to be made based on feedback after
manufacture. Meanwhile, development may continue for other projects using the
same IP. As a result, third-party IP used in hardware projects require distinct
versions in the repository.

Details

Hardware development which involves third-party RTL, source, schematics, or other files, should generally follow go/thirdparty.

Below are the exceptions and special requirements for third-party hardware directories.

Four versions allowed

• Third_party hardware directories can have up to four folders, each containing a unique version.
• The root directory must contain METADATA, OWNERS and README.md covering all versions of the IP.
• Each version of the IP must have its own BUILD, METADATA and LICENSE.
• Previous versions of the IP must be deleted in the following cases:
  1. Prior to checking in more versions once the four version limit is reached.
  2. Once a version no longer required to develop active products.

Naming convention

The library name and corresponding directory name must include the vendor name, IP name and optionally the project name (for IPs used exclusively by one project) using the following convention:

 <VendorNameInCamelCase>_<ip_name_snake>[_<project_name>]

Each version must have a unique identifier, ideally matching the vendor's IP version if available.

Example

//piper/.../VendorName_ip_name
│   METADATA
|   OWNERS
|   README.md
│
└───ver_1
|   |   BUILD
│   │   METADATA
│   │   LICENSE
|
└───ver_2
|   |   BUILD
|   │   METADATA
|   │   LICENSE
|
└───ver_3
|   |   BUILD
│   │   METADATA
│   │   LICENSE

METADATA

General details for third_party METADATA can be found at go/thirdparty/metadata.

• third_party/hardware/METADATA must:
  1. Set the type field to GROUP

third_party: { type: GROUP }

• third_party/hardware/VendorName_ip_name/METADATA should indicate that the multiple version exception applies to your IP:
  1. Set the type field to VERSIONS
  2. Refer to this document in the approval field

third_party: {
  type: VERSIONS
  multiple_versions {
    type: PERMANENT # Maximum of four versions at a time
    approval: "http://linkremoved/"
  }
}

• third_party/hardware/VendorName_ipname/ver*/METADATA must:
  1. Set the type field to PACKAGE
  2. Identify a version that matches the directory name
  3. Document the last upgrade date

third_party: {
  type: PACKAGE # PACKAGE is the default type so it may be omitted
  version: "identifier" # Must match the <identifier> in the directory name
  last_upgrade_date: {
    year: yyyy
    month: mm
    day: dd
  }
}

OWNERS

At least four hardware FTEs must be in //piper/.../OWNERS at all times. Their role will be to review and approve CLs based on the general third_party policies as well as the differences for hardware. New packages will still require third-party-removed approval.

Use Piper Branches After Deployment

Once hardware is deployed, a project team may require a specific version of third_party IP for field debug support. Teams may use a Piper overlay branch of the tree for this purpose and avoid exceeding the limit of four versions at HEAD.