# Upstream GPGPU-Sim: pin, provenance and patch policy

> Public-safe reference for the upstream checkout used by this overlay.

## 1. Pinned identity

| Field | Value |
|---|---|
| Repository | `https://github.com/gpgpu-sim/gpgpu-sim_distribution` |
| Commit | `90ec3399763d7c8512cfe7dc193473086c38ca38` |
| Tag | `v4.0.1` |
| In-tree version string | `GPGPU-Sim Simulator Version 4.0.0` |
| License | BSD-3-Clause (Copyright 2009-2011 Tor M. Aamodt and The University of British Columbia) |
| Checkout location | `gpgpu-sim/upstream/` (gitignored; never committed) |

The pin is reproduced by `setup.sh` (constant `PIN`). A fresh run clones into
`upstream/`, checks out the pin detached, applies `patches/`, and builds.
Re-running verifies the checkout is still at the pin and that every patch is
either applicable or already applied, so the process is idempotent.

## 2. Clone source

`setup.sh` clones from the upstream URL above by default. A local mirror is
used **only** when `GPGPUSIM_CLONE_SOURCE=<path-or-url>` is set explicitly
(unset by default); no host path is hardcoded or guessed. The clone source
never changes the pin: the checkout is always forced to `90ec339`. This is a
build convenience only; upstream code is never modified in place by hand.

## 3. `origin/dev` (4.2.0): not checked out, tracked as a reference

The repository's `origin/dev` branch is a later line (in-tree version string
`4.2.0`) that adds, among other things, AccelWattch power modeling, an Ampere
RTX 3060 (SM86) tested configuration, and Turing L1 fixes. It is **not** the
pin and is not used by Phase 0. It is recorded here because Phase 1/2 may
rebase selected changes (architecture config, L1 fixes) into our patch set
rather than adopting the whole branch. Any such rebase must be an explicit,
recorded decision with the same reproducibility guarantees (new pin + patch
set + test evidence), never a silent branch switch.

## 4. How our changes are applied

Design rule: upstream history is never forked. Our work lives entirely in this
overlay and reaches the upstream tree as **patches**, in this order:

1. `setup.sh` clones/checks out the pin.
2. `patches/*.patch` are applied in lexical filename order
   (`0001-*`, `0002-*`, ...) with `git apply`.
3. For each patch, `git apply --check` decides "apply"; otherwise
   `git apply --reverse --check` decides "already applied"; if neither holds,
   `setup.sh` fails loudly rather than guessing.
4. New source trees that are not clean patches ship as patches too (a patch
   can add files). There is no separate overlay-copy step in Phase 0.

The first expected patch set is the CUDA-12 build/runtime port (WP0.1), which
makes `setup_environment`, the PTX path and `cuobjdump` handling work on this
host's CUDA. Until those patches exist the default build correctly refuses to
proceed with a clear error.

To reset the checkout: `./setup.sh --reclone` (destroys `upstream/` and clones
fresh). Nothing outside `gpgpu-sim/upstream/` and `gpgpu-sim/build/` is
touched by the build; both are gitignored.

## 5. Reproducibility checks

```bash
git -C gpgpu-sim/upstream rev-parse HEAD          # must equal the pin above
git -C gpgpu-sim/upstream status --porcelain      # patch-applied delta expected
sha256sum gpgpu-sim/patches/*.patch               # record with any result
```

Build logs are written to `gpgpu-sim/build/build.log` and are not committed.