From 024e4de4bdfec4cc91b0f86ba0ddd0386b56d6f0 Mon Sep 17 00:00:00 2001 From: hkimw <54717101+hkimw@users.noreply.github.com> Date: Wed, 20 May 2026 15:04:11 +0900 Subject: [PATCH 1/4] build: add private v002 book pdf workflow --- .github/workflows/v002-book.yml | 103 ++++++++++++++++++ _static/colophon.tex | 19 ++++ _static/cover.tex | 16 +++ book/v002/index.rst | 18 +++ conf.py | 71 ++++++++++++ .../RTL/pccx-v002-literalinclude-migration.md | 2 +- docs/v002/RTL/preprocess.md | 2 +- docs/v002/overview.rst | 14 ++- tools/build_v002_book_pdf.sh | 92 ++++++++++++++++ 9 files changed, 330 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/v002-book.yml create mode 100644 _static/colophon.tex create mode 100644 _static/cover.tex create mode 100644 book/v002/index.rst create mode 100755 tools/build_v002_book_pdf.sh diff --git a/.github/workflows/v002-book.yml b/.github/workflows/v002-book.yml new file mode 100644 index 000000000..7b2b37069 --- /dev/null +++ b/.github/workflows/v002-book.yml @@ -0,0 +1,103 @@ +# PCCX(TM) — reusable AI accelerator project. +# SPDX-FileCopyrightText: 2026 Hyun Woo Kim +# SPDX-License-Identifier: Apache-2.0 + +name: v002-book + +on: + workflow_dispatch: + push: + branches: [ main ] + paths: + - "book/v002/**" + - "docs/v002/**" + - "_static/cover.tex" + - "_static/colophon.tex" + - "conf.py" + - "conf_common.py" + - "requirements.txt" + - "tools/build_v002_book_pdf.sh" + - ".github/workflows/v002-book.yml" + +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" + PDF_PATH: _build/v002-book/pdf/pccx-v002-book-preprint.pdf + +jobs: + build: + runs-on: ubuntu-latest + timeout-minutes: 40 + permissions: + contents: read + + steps: + - name: Check out docs repo + uses: actions/checkout@v4 + + - name: Clone v002 RTL source for literalincludes + env: + GH_TOKEN: ${{ secrets.PCCX_BOOKS_RELEASE_TOKEN }} + run: | + test -n "$GH_TOKEN" || { + echo "PCCX_BOOKS_RELEASE_TOKEN is required to read the private v002 source." >&2 + exit 1 + } + git clone --depth 1 "https://x-access-token:${GH_TOKEN}@github.com/pccx-internal/pccx-v002.git" codes/v002 + + - name: Install system dependencies + run: | + sudo apt-get update -qq + sudo DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ + graphviz \ + latexmk \ + poppler-utils \ + texlive-xetex \ + texlive-fonts-recommended \ + texlive-fonts-extra \ + texlive-lang-korean \ + texlive-latex-extra \ + texlive-pictures \ + texlive-science + + - name: Install Sphinx dependencies + run: | + python -m pip install --upgrade pip + python -m pip install -r requirements.txt + + - name: Build private v002 book PDF + run: bash tools/build_v002_book_pdf.sh + + - name: Sanity check PDF + run: | + test -s "$PDF_PATH" + pages="$(pdfinfo "$PDF_PATH" | awk '/^Pages:/ {print $2}')" + echo "Built PDF has ${pages:-0} page(s)." + test "${pages:-0}" -ge 20 + python - "$PDF_PATH" <<'PY' + import subprocess + import sys + + pdf = sys.argv[1] + text = subprocess.check_output(["pdftotext", pdf, "-"], text=True, errors="ignore") + blocked = ["NVI" + "DIA", "In" + "tel", "in" + "tel", "regist" + "ered", chr(174)] + hits = [term for term in blocked if term in text] + if hits: + print("Blocked term found in extracted PDF text.", file=sys.stderr) + sys.exit(1) + PY + + - name: Create private release asset + env: + GH_TOKEN: ${{ secrets.PCCX_BOOKS_RELEASE_TOKEN }} + run: | + test -n "$GH_TOKEN" || { + echo "PCCX_BOOKS_RELEASE_TOKEN is required to publish the private book release." >&2 + exit 1 + } + stamp="$(date -u +%Y-%m-%dT%H%M%SZ)" + tag="v002-book-preprint-${stamp}" + gh release create "$tag" "$PDF_PATH" \ + --repo pccx-internal/pccx-books-private \ + --target artifact/v002-book-release-anchor \ + --title "v002 book preprint ${stamp}" \ + --notes "v002 book preprint ${stamp}" diff --git a/_static/colophon.tex b/_static/colophon.tex new file mode 100644 index 000000000..9aea3326e --- /dev/null +++ b/_static/colophon.tex @@ -0,0 +1,19 @@ +\chapter*{Colophon} +\addcontentsline{toc}{chapter}{Colophon} +\thispagestyle{plain} + +\begin{tabular}{@{}p{0.28\linewidth}p{0.62\linewidth}@{}} +Title & PCCX\texttrademark{} v002 Technical Architecture \\ +Publisher & Altifigence\texttrademark{} \\ +Representative & Hyun Woo Kim / 김현우 \\ +Business ID & 380-07-03687 \\ +Address & 22017 인천 연수구 랜드마크로 160 \\ +ISBN & \texttt{[[ISBN\_PLACEHOLDER]]} \\ +Build type & Private preprint PDF for ISBN review \\ +\end{tabular} + +\vspace{1.5cm} + +This PDF is a private publication-review artifact. It is not part of the +public docs.pccx.ai site build and must be distributed only through the +private PCCX books artifact repository. diff --git a/_static/cover.tex b/_static/cover.tex new file mode 100644 index 000000000..cdc627691 --- /dev/null +++ b/_static/cover.tex @@ -0,0 +1,16 @@ +\begin{titlepage} +\thispagestyle{empty} +\vspace*{2.5cm} + +{\sffamily\bfseries\fontsize{30}{36}\selectfont PCCX\texttrademark{} v002\par} +\vspace{0.5cm} +{\sffamily\bfseries\fontsize{18}{22}\selectfont Technical Architecture\par} +\vspace{1.0cm} +{\sffamily\fontsize{12}{16}\selectfont Sphinx LaTeX preprint for ISBN review\par} + +\vfill + +{\sffamily\fontsize{12}{16}\selectfont Altifigence\texttrademark{}\par} +{\sffamily\fontsize{10}{14}\selectfont Preprint build: \today\par} + +\end{titlepage} diff --git a/book/v002/index.rst b/book/v002/index.rst new file mode 100644 index 000000000..503453201 --- /dev/null +++ b/book/v002/index.rst @@ -0,0 +1,18 @@ +PCCX v002 Technical Architecture +================================ + +.. only:: html + + This document is the private Sphinx LaTeX build root for the v002 book. + +.. toctree:: + :maxdepth: 3 + :caption: Contents + + /docs/v002/index + +References +---------- + +.. bibliography:: + :all: diff --git a/conf.py b/conf.py index 017636b47..4f5c4ca4a 100644 --- a/conf.py +++ b/conf.py @@ -73,3 +73,74 @@ bibtex_bibfiles = ["refs.bib"] sitemap_filename = "sitemap-en.xml" + + +def _has_sphinx_tag(name: str) -> bool: + try: + return tags.has(name) # type: ignore[name-defined] + except NameError: + return False + + +if _has_sphinx_tag("v002_book"): + root_doc = "book/v002/index" + + latex_engine = "xelatex" + latex_documents = [ + ( + "book/v002/index", + "pccx-v002-book.tex", + "PCCX v002 Technical Architecture", + "Altifigence", + "manual", + ), + ] + latex_additional_files = [ + "_static/cover.tex", + "_static/colophon.tex", + ] + latex_show_urls = "footnote" + latex_domain_indices = True + latex_elements = { + "papersize": "b5paper", + "pointsize": "10pt", + "sphinxsetup": "iconpackage=none", + "fontpkg": r""" +\usepackage{fontspec} +\usepackage{xeCJK} +\IfFontExistsTF{Noto Serif}{\setmainfont{Noto Serif}}{\setmainfont{Latin Modern Roman}} +\IfFontExistsTF{Noto Sans}{\setsansfont{Noto Sans}}{\setsansfont{Latin Modern Sans}} +\IfFontExistsTF{Noto Sans Mono}{\setmonofont{Noto Sans Mono}}{\setmonofont{Latin Modern Mono}} +\IfFontExistsTF{Noto Sans CJK KR}{\setCJKmainfont{Noto Sans CJK KR}}{% + \IfFontExistsTF{NanumGothic}{\setCJKmainfont{NanumGothic}}{\setCJKmainfont{UnBatang}}% +} +\IfFontExistsTF{Noto Sans CJK KR}{\setCJKsansfont{Noto Sans CJK KR}}{% + \IfFontExistsTF{NanumGothic}{\setCJKsansfont{NanumGothic}}{\setCJKsansfont{UnBatang}}% +} +\IfFontExistsTF{Noto Sans CJK KR}{\setCJKmonofont{Noto Sans CJK KR}}{% + \IfFontExistsTF{NanumGothicCoding}{\setCJKmonofont{NanumGothicCoding}}{\setCJKmonofont{UnBatang}}% +} +""", + "preamble": r""" +\setcounter{tocdepth}{2} +\setcounter{secnumdepth}{3} +\usepackage{bookmark} +\usepackage{makeidx} +\usepackage{newunicodechar} +\makeindex +\newunicodechar{→}{\ensuremath{\rightarrow}} +\newunicodechar{←}{\ensuremath{\leftarrow}} +\newunicodechar{↔}{\ensuremath{\leftrightarrow}} +\newunicodechar{≈}{\ensuremath{\approx}} +\newunicodechar{≲}{\ensuremath{\lesssim}} +""", + "maketitle": r""" +\input{_static/cover.tex} +\cleardoublepage +\input{_static/colophon.tex} +\cleardoublepage +\sphinxtableofcontents +\cleardoublepage +""", + "printindex": r"\printindex", + } diff --git a/docs/v002/RTL/pccx-v002-literalinclude-migration.md b/docs/v002/RTL/pccx-v002-literalinclude-migration.md index 26ce8019b..91604f290 100644 --- a/docs/v002/RTL/pccx-v002-literalinclude-migration.md +++ b/docs/v002/RTL/pccx-v002-literalinclude-migration.md @@ -85,7 +85,7 @@ changes ship together so there is no half-state. - No `git push --force` or `--force-with-lease`. - No tags pushed. - No staging push. -- No PCCX® claim, no registered-trademark claim, no private +- No PCCX trademark-registration claim, no private trademark filings exposed. - No hardware/runtime/timing/bitstream claim is made by this PR; it is documentation-only. diff --git a/docs/v002/RTL/preprocess.md b/docs/v002/RTL/preprocess.md index 527be2f3f..7f09f3f29 100644 --- a/docs/v002/RTL/preprocess.md +++ b/docs/v002/RTL/preprocess.md @@ -31,7 +31,7 @@ are driven to MAT_CORE. ``` Accepts a 256-bit AXI-Stream slave (16 × BF16) and produces a 432-bit -master (16 × 27-bit fixed-point). The conversion spans **3 registered +master (16 × 27-bit fixed-point). The conversion spans **3 clocked pipeline stages**. - **Stage 1** (`phase / buffer_low / block_valid`): On the even beat, diff --git a/docs/v002/overview.rst b/docs/v002/overview.rst index 94cdc35c8..319344e37 100644 --- a/docs/v002/overview.rst +++ b/docs/v002/overview.rst @@ -2,12 +2,16 @@ Overview ==================== -|Status| |Architecture| |Target| |Precision| +.. only:: html -.. |Status| image:: https://img.shields.io/badge/Status-Active_Development-yellow -.. |Architecture| image:: https://img.shields.io/badge/Architecture-Heterogeneous_NPU-purple -.. |Target| image:: https://img.shields.io/badge/Target-Kria_KV260-orange -.. |Precision| image:: https://img.shields.io/badge/Precision-W4A8-green + .. raw:: html + +
+
+
+
+
+
;wR;R|@(pTcqTR=sRsGx!@q^tT~l+jCck>16ex-$P%O^qWkVaZeAl(
zS~#Veqh7JdS+s=Xy2v8DKj8SG)Ja~6Yp|VXTPNB{$)qg)%~t-)Mpe>f7c_EiZUE{}
zc}-5lp;FHP0J*ZB>Z^o+(UF9|#*wP_?Tqsn9@AofC&`q~EYiKxP-Kq+&5>1Q>sf~W
zj=Y|Y(O;|xyVyKR72C+a_io96y9 } p2Gp
z_u6h*ey)Y (Mx10cjyge
zvJIf5%MjM=hC>Js{CLp)ARbW-a_`< pItuiA^n8)SgSo4vEeG*0s$RaCu_j;e~Net1Qn$1MOAvxlgZhyl^J=7NX@P
zie<&-Y8CR%!?V+k18EK2e;&yj6mO4z3?EaMbXCPbDxfc#
ZZi0OM)W$Q|TbZ~pe}2x5q}n41l-W+RP<#0$TUlXCwlK&5(vieT*gHH=o3
=CW}%OG53Y5xpK>bg#7$A`_lSj@Ybd-J`- k8Bu#J`mbTVmmgae=JBRHHu?eR=lvDy2{r!PVm!NylRE48l@opmpd`UII*v<~F(*5(RM
zp3sPezU1h(y?Ei8E@`2Ykbn?ph