From 9337bf2516b4e0876d5308ec15939cb2dc9e6ab8 Mon Sep 17 00:00:00 2001
From: Kayce Basques <kayce@google.com>
Date: Sun, 5 Jan 2025 09:04:00 -0800
Subject: [PATCH] docs: Add toolchain homepage
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bug: 373454866

Change-Id: Iea27fe90e0f3ff0522f5becc9e7ed57d74b3eb72
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/247593
Lint: Lint 🤖 <android-build-ayeaye@system.gserviceaccount.com>
Presubmit-Verified: CQ Bot Account <pigweed-scoped@luci-project-accounts.iam.gserviceaccount.com>
Commit-Queue: Auto-Submit <auto-submit@pigweed-service-accounts.iam.gserviceaccount.com>
Pigweed-Auto-Submit: Kayce Basques <kayce@google.com>
Reviewed-by: Amit Uttamchandani <amituttam@google.com>
---
 docs/BUILD.bazel   |  1 +
 docs/BUILD.gn      |  1 +
 docs/conf.py       |  6 +++-
 docs/index.rst     |  1 +
 docs/toolchain.rst | 81 ++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 89 insertions(+), 1 deletion(-)
 create mode 100644 docs/toolchain.rst

diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
index 6d55939db..cddf284aa 100644
--- a/docs/BUILD.bazel
+++ b/docs/BUILD.bazel
@@ -43,6 +43,7 @@ sphinx_docs_library(
         "python_build.rst",
         "targets.rst",
         "third_party_support.rst",
+        "toolchain.rst",
     ],
     strip_prefix = "docs/",
     target_compatible_with = incompatible_with_mcu(),
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index f7a813616..5e064e3bb 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -435,6 +435,7 @@ pw_doc_gen("docs") {
     "python_build.rst",
     "targets.rst",
     "third_party_support.rst",
+    "toolchain.rst",
   ]
   output_directory = target_gen_dir
   deps = [
diff --git a/docs/conf.py b/docs/conf.py
index 70f729da0..cbfcdfd11 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -222,7 +222,11 @@ def pygments_monkeypatch_style(mod_name, cls):
 html_baseurl = 'https://pigweed.dev/'
 
 # Hide "Section Navigation" on homepage and changelog.
-html_sidebars = {'index': [], 'changelog': []}
+html_sidebars = {
+    'index': [],
+    'changelog': [],
+    'toolchain': [],
+}
 
 html_context = {
     'default_mode': 'dark',
diff --git a/docs/index.rst b/docs/index.rst
index a8504d9b6..165bfe328 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -193,6 +193,7 @@ Talk to us
    Source code <https://cs.pigweed.dev/pigweed>
    docs/showcases/index
    docs/concepts/index
+   Toolchain <toolchain>
    docs/3p/index
    docs/community/index
    Developing & contributing <docs/contributing/index>
diff --git a/docs/toolchain.rst b/docs/toolchain.rst
new file mode 100644
index 000000000..b2e63eb10
--- /dev/null
+++ b/docs/toolchain.rst
@@ -0,0 +1,81 @@
+.. _toolchain:
+
+=================
+Pigweed Toolchain
+=================
+Pigweed Toolchain is an LLVM/Clang toolchain for embedded use cases.
+
+.. _toolchain-background:
+
+----------
+Background
+----------
+Our toolchain philosophy is to co-evolve the support for embedded use cases in
+the LLVM project as we onboard new projects to use the Clang/LLVM toolchain
+distributed by us. Teams at Google that we partner with make contributions to the
+LLVM project regularly. Recent contributions include:
+
+* Compiler optimizations
+* LLVM ``libc`` library support
+* Improvements to the LLD linker
+
+.. _live at HEAD: https://abseil.io/about/philosophy#we-recommend-that-you-choose-to-live-at-head
+
+We follow the `live at HEAD`_ model and do all development in LLVM which enables
+us to rapidly adopt new features and provide fast feedback to the LLVM community.
+We continuously build new versions of the Clang toolchain binaries and distribute
+them to our users. Pigweed's toolchain version is periodically updated along with
+code changes necessary to the Pigweed codebase itself to be compatible with and
+take advantage of new toolchain features as soon as they land.
+
+For more information, check out the following presentation:
+
+.. raw:: html
+
+   <iframe width="560" height="315"
+       src="https://www.youtube.com/embed/0HvgvBUPTyw"
+       title="LLVM Toolchain for Embedded Systems"
+       frameborder="0"
+       allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+       referrerpolicy="strict-origin-when-cross-origin"
+       allowfullscreen></iframe>
+
+.. _toolchain-prebuilts:
+
+---------
+Prebuilts
+---------
+.. _CIPD Packages: https://chrome-infra-packages.appspot.com/p/fuchsia/third_party/clang
+
+The toolchain can be downloaded from `CIPD Packages`_. It includes
+a cross-compiler that can target the following architectures.
+
+Embedded targets:
+
+* ARM 32-bit
+
+  * ARMv6
+
+  * ARMv7
+
+  * ARMv8
+
+* RISC-V 32-bit
+
+Host targets:
+
+* Linux
+* Windows\ :sup:`1`
+* macOS\ :sup:`2`
+
+:sup:`1` Contains some limitations around user-side licensing.
+
+:sup:`2` MLInliner is not supported yet.
+
+.. _toolchain-support:
+
+-------
+Support
+-------
+`File a bug <https://pwbug.dev>`_ or talk to the Pigweed
+team on `Discord <https://discord.com/invite/M9NSeTA>`_.