From 92bc980d1de72614e549acd3f577e25afd291c22 Mon Sep 17 00:00:00 2001
From: Tapasvi Patel <133996364+tapspatel@users.noreply.github.com>
Date: Wed, 28 Aug 2024 13:38:53 -0500
Subject: [PATCH] #521: Added CI docs on how to add a test and how CI
 infrastructure works (#522)

---
 .github/workflows/build-and-test.yml |   4 +-
 .github/workflows/on-push.yml        |   3 +
 docs/src/SUMMARY.md                  |   1 +
 docs/src/ci.md                       | 124 +++++++++++++++++++++++++++
 4 files changed, 130 insertions(+), 2 deletions(-)
 create mode 100644 docs/src/ci.md

diff --git a/.github/workflows/build-and-test.yml b/.github/workflows/build-and-test.yml
index b5af5b113..3b9166d2b 100644
--- a/.github/workflows/build-and-test.yml
+++ b/.github/workflows/build-and-test.yml
@@ -12,8 +12,8 @@ jobs:
       fail-fast: false
       matrix:
         build: [
-          {runs-on: self-hosted, enable_perf: OFF, name: "run"},
-          {runs-on: self-hosted, enable_perf: ON, name: "perf"},
+          {runs-on: builder, enable_perf: OFF, name: "run"},
+          {runs-on: builder, enable_perf: ON, name: "perf"},
         ]
 
     runs-on: ${{ matrix.build.runs-on }}
diff --git a/.github/workflows/on-push.yml b/.github/workflows/on-push.yml
index a6a0e24b4..ff7bfab98 100644
--- a/.github/workflows/on-push.yml
+++ b/.github/workflows/on-push.yml
@@ -18,3 +18,6 @@ jobs:
   docker-build:
     uses: ./.github/workflows/docker-build.yml
     secrets: inherit
+  build-and-test:
+    uses: ./.github/workflows/build-and-test.yml
+    secrets: inherit
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 29eec9d1f..d962cd1fe 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -12,6 +12,7 @@
   - [ttrt](./ttrt.md)
   - [tt-explorer](./tt-explorer.md)
 - [Flatbuffers](./flatbuffers.md)
+- [CI](./ci.md)
 - [Additional Reading](./additional-reading.md)
 - [Code of Conduct](./code-of-conduct.md)
 
diff --git a/docs/src/ci.md b/docs/src/ci.md
new file mode 100644
index 000000000..89553e8cb
--- /dev/null
+++ b/docs/src/ci.md
@@ -0,0 +1,124 @@
+# `ci`
+
+Our CI infrastructure is currently hosted on cloud. Cloud machines are used and linked as GitHub runners.
+
+## Key Words
+### Target Silicon (coming soon)
+```bash
+- 1:1 mapping to unique system-desc (this is because an n150 card can have different harvested rows)
+```
+
+### Target Family
+```bash
+- product type (n150, n300)
+```
+
+### Target Capabilities (coming soon)
+```bash
+- describes testable traits of Target Family
+n150: {
+    test params to use if running on n150
+}
+n300: {
+    test params to use if running on n150
+}
+```
+
+### Test Capabilities (coming soon)
+```bash
+- set of target capabilities defined in the test
+- test will populate certain parameters depending on the Target Family/Target Silicon it is running on
+```
+
+## GitHub Runner CI Tags
+### Runner Use
+There are 2 types of runner machines. Builders build offline and runners are silicon machines.
+```bash
+- builder
+- runner
+```
+
+### Runner Type
+There are 2 runner types. Bare metals are standalone and virtual machines are kubernetes pods.
+```bash
+- bare-metal
+- virtual-machine
+```
+
+### Architecture
+Supported architectures
+```bash
+- wormhole_b0
+- blackhole (coming soon)
+```
+
+### Pipeline Type
+Supported pipelines
+```bash
+- perf
+- functional
+```
+
+### Active
+Defines whether a runner is in service or taken out of service for maintenance
+```bash
+- in-service
+- out-of-service
+```
+
+### Target Family
+Supported configurations of machines
+```bash
+- n150
+- n300
+- t3000 (coming soon)
+- tg (coming soon)
+- tgg (coming soon)
+```
+
+### Target Silicon (coming soon)
+```bash
+-silicon-n150-0 (0th row harvested)
+-silicon-n150-1 (1th row harvested)
+-silicon-n300-0-0 (0th row harvested both chips)
+```
+
+## Pipeline durations
+```bash
+- push: every push to main
+- pr: every PR
+```
+
+## CI Test Flow
+```bash
+1. GitHub runner
+- build tt-mlir
+- build ttrt
+- upload artifacts
+
+2. Silicon runner
+- download tt-mlir / ttrt artifacts
+- ttrt generate system desc
+- llvm-lit runs all unit test, including silicon ones to generate flatbuffers (will only generate ones that are supported for that test file)
+- ttrt runs generated flatbuffers
+```
+
+## Adding a test
+When adding a test, you can specify when the test should run and what values it should inherit. The test defines how it should run, not the infrastructure. The infrastructure will execute what the test defines. For now, if you specify nothing, it will run on all default parameters.
+Note: if you provide a target family, then it will be default run on any target silicon machine. If you need a specific target silicon machine (eg one with 1st row harvested), specify it in Target Silicon.
+Note: if you specify perf pipeline, it will automatically run on a bare metal machine
+Default parameters
+```bash
+[Architecture]: [wormhole_b0]
+[Pipeline]: [functional, perf]
+[Target Family]: [n150, n300]
+[Target Silicon]: []
+[Duration]: [push]
+```
+
+```bash
+Location: test/ttmlir/Silicon
+File Type: .mlir
+REQUIRES: [Architecture] [Pipeline] [Target Family] [Target Silicon] [Duration] (coming soon)
+UNSUPPORTED: [Target Family] [Target Silicon] (coming soon)
+```