diff --git a/.github/workflows/v002-book.yml b/.github/workflows/v002-book.yml new file mode 100644 index 00000000..a3bf0a88 --- /dev/null +++ b/.github/workflows/v002-book.yml @@ -0,0 +1,104 @@ +# 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/cover/**" + - "_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", "reg" + "istered", 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 00000000..7323ebce --- /dev/null +++ b/_static/colophon.tex @@ -0,0 +1,21 @@ +\chapter*{Colophon} +\addcontentsline{toc}{chapter}{Colophon} +\thispagestyle{plain} + +\begin{tabular}{@{}p{0.28\linewidth}p{0.62\linewidth}@{}} +Title & \texttt{[[TITLE\_PLACEHOLDER]]} \\ +Subtitle & \texttt{[[SUBTITLE\_PLACEHOLDER]]} \\ +Author & \texttt{[[AUTHOR\_PLACEHOLDER]]} \\ +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 00000000..fbb96204 --- /dev/null +++ b/_static/cover.tex @@ -0,0 +1,41 @@ +\begin{titlepage} +\thispagestyle{empty} +\begingroup +\setlength{\parindent}{0pt} +\begin{tikzpicture}[remember picture,overlay] +\node[inner sep=0pt] at (current page.center) + {\includegraphics[height=\paperheight]{_static/cover/cover-art.jpg}}; + +\node[ + anchor=north west, + align=left, + inner sep=0pt, + text=black, + text width=0.76\paperwidth +] at ([xshift=14mm,yshift=-14mm]current page.north west) {% + {\pccxcovermono\bfseries\fontsize{20}{24}\selectfont [[TITLE\_PLACEHOLDER]]\par} + \vspace{3mm} + {\pccxcoverfont\bfseries\fontsize{12}{16}\selectfont [[SUBTITLE\_PLACEHOLDER]]\par} + \vspace{4mm} + {\pccxcoverfont\fontsize{9}{12}\selectfont Private Sphinx LaTeX preprint for ISBN review\par} +}; + +\node[ + anchor=south west, + align=left, + inner sep=0pt, + text=black, + text width=0.76\paperwidth +] at ([xshift=14mm,yshift=16mm]current page.south west) {% + {\pccxcoverfont\fontsize{10}{13}\selectfont [[AUTHOR\_PLACEHOLDER]]\par} + \vspace{1mm} + {\pccxcoverfont\fontsize{10}{13}\selectfont Altifigence\texttrademark{}\quad 2026\par} + \vspace{1mm} + {\pccxcovermono\fontsize{8}{11}\selectfont ISBN [[ISBN\_PLACEHOLDER]]\par} +}; +\end{tikzpicture} + +\null +\endgroup + +\end{titlepage} diff --git a/_static/cover/cover-art.jpg b/_static/cover/cover-art.jpg new file mode 100644 index 00000000..e5558f4c Binary files /dev/null and b/_static/cover/cover-art.jpg differ diff --git a/book/v002/index.rst b/book/v002/index.rst new file mode 100644 index 00000000..50345320 --- /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 017636b4..d674866b 100644 --- a/conf.py +++ b/conf.py @@ -73,3 +73,97 @@ 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 not _has_sphinx_tag("v002_book"): + exclude_patterns = [ + *exclude_patterns, + "book", + "book/**", + ] + + +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/cover/cover-art.jpg", + "_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} +\usepackage{tikz} +\IfFontExistsTF{Pretendard}{\newfontfamily\pccxcoverfont{Pretendard}}{% + \IfFontExistsTF{Noto Sans CJK KR}{\newfontfamily\pccxcoverfont{Noto Sans CJK KR}}{% + \IfFontExistsTF{NanumGothic}{\newfontfamily\pccxcoverfont{NanumGothic}}{\newfontfamily\pccxcoverfont{Latin Modern Sans}}% + }% +} +\IfFontExistsTF{Courier New}{\newfontfamily\pccxcovermono{Courier New}}{% + \IfFontExistsTF{Noto Sans Mono}{\newfontfamily\pccxcovermono{Noto Sans Mono}}{\newfontfamily\pccxcovermono{Latin Modern Mono}}% +} +\titleformat{\chapter}[display] + {\normalfont\pccxcovermono\bfseries\huge} + {\chaptertitlename\ \thechapter} + {12pt} + {\Huge} +\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/conf_common.py b/conf_common.py index 32ebfcde..95825507 100644 --- a/conf_common.py +++ b/conf_common.py @@ -112,6 +112,7 @@ "Makefile", # planning / audit markdown at the repo root — not part of the docs site "USER_ACTIONS.md", + "KOREAN_PUBLICATION_EDIT_REPORT.md", "pccx_master_roadmap_final.md", "pccx_v002_extended_20toks_plan.md", "tinynpu_v003_gemma4_e4b_plan*.md", # the (1) variant uses a paren diff --git a/docs/v002/RTL/pccx-v002-literalinclude-migration.md b/docs/v002/RTL/pccx-v002-literalinclude-migration.md index 26ce8019..91604f29 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 527be2f3..7f09f3f2 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 94cdc35c..319344e3 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 + +
+
+
+
+
+