diff --git a/.rstcheck.cfg b/.rstcheck.cfg index ee03cb6e5..cef15ebdf 100644 --- a/.rstcheck.cfg +++ b/.rstcheck.cfg @@ -1,5 +1,5 @@ [rstcheck] -ignore_directives = ifconfig,tabs,tab,group-tab,code-tab +ignore_directives = ifconfig,tabs,tab,group-tab,code-tab,graphviz # ignore the following languages because they require external compilers and # snippets in this repo depend on external code ignore_languages = c,cpp,c++ diff --git a/conf.py b/conf.py index 180aca691..4270352f0 100644 --- a/conf.py +++ b/conf.py @@ -39,6 +39,7 @@ 'sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', + 'sphinx.ext.graphviz', 'sphinx_rtd_theme', 'sphinx_tabs.tabs', 'sphinx_copybutton' @@ -253,6 +254,9 @@ # Suppress warnings about excluded documents because every device gets a different toc tree suppress_warnings = ['toc.excluded'] +# Render graphviz diagrams as SVG so that hyperlinks in diagrams are clickable +graphviz_output_format = 'svg' + # -- Tag file loader ------------------------------------------------------ FAMILY = os.environ.get("DEVFAMILY", "") diff --git a/docker/Dockerfile b/docker/Dockerfile index 7edba1ec2..28fd1101c 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -8,6 +8,7 @@ RUN apk add --no-cache \ diffutils \ dumb-init \ git \ + graphviz \ make \ py3-pip \ ripgrep \ diff --git a/source/buildroot/Overview.rst b/source/buildroot/Overview.rst index 5e338b301..b5c355c22 100644 --- a/source/buildroot/Overview.rst +++ b/source/buildroot/Overview.rst @@ -8,7 +8,48 @@ cross-compiled toolchains, root filesystems, Linux kernels, and bootloaders. Buildroot is highly customizable, allowing developers to tailor their Linux environment to meet the specific needs of their embedded projects. -Buildroot official Git repository is hosted at `Gitlab/Buildroot `__. + +************************************** +Buildroot Architecture for TI Devices +************************************** + +The diagram below shows the Buildroot-based Linux embedded software distribution main components for TI devices. + +The open-source Linux\ :sup:`®` distribution, based on the Buildroot build system, running on the Arm\ :sup:`®` Cortex\ :sup:`®`\-A processors, includes: + +- **TI BSP Components** — the Texas Instruments Board Support Package, comprising: + + - The boot chain based on **TF-A** (Trusted Firmware-A) and **U-Boot**. + - The secure monitor based on **TF-A** and **OP-TEE**, running on the Arm\ :sup:`®` + Cortex\ :sup:`®`\-A in secure mode. + - The **OP-TEE** secure OS running on the Arm\ :sup:`®` Cortex\ :sup:`®`\-A in secure mode, + providing a Trusted Execution Environment (TEE) for Trusted Applications. + - The **Linux Kernel** and **TI Kernel Drivers** running on the Arm\ :sup:`®` + Cortex\ :sup:`®`\-A in non-secure mode, along with board-specific **Device Trees**. + - The **TI Linux Firmware** providing co-processor firmwares + (not applicable for AM62Lx-EVM). + +- **Buildroot Build System** — consisting of: + + - **Buildroot Core**: the upstream Buildroot framework that drives the entire build. + - **Buildroot External-TI**: the TI-specific external tree + (`buildroot-external-TI `__) + that adds TI board configurations, packages, and patches without modifying upstream Buildroot. + +- **Applications** — the user-space software layer built on top of the BSP, including + GUI applications, custom applications, Trusted Applications running under OP-TEE, + and middleware and libraries. + +- **Build Artifacts** — the outputs produced by the Buildroot build system: an SD card + image, individual boot artifacts, and a root filesystem. + +.. note:: + + Each component in the diagram below is a **clickable hyperlink** that navigates + directly to the corresponding source repository or documentation. + +.. graphviz:: ../graphviz/Buildroot_architecture.gv + :caption: Buildroot-based Linux Architecture for TI Devices ************************* Key Features of Buildroot diff --git a/source/graphviz/Buildroot_architecture.gv b/source/graphviz/Buildroot_architecture.gv new file mode 100644 index 000000000..c3767e446 --- /dev/null +++ b/source/graphviz/Buildroot_architecture.gv @@ -0,0 +1,348 @@ +digraph buildroot_architecture { + rankdir=TB; + graph [splines=ortho, nodesep=0.5, ranksep=0.7, + fontname="Arial", pad=0.5, bgcolor="white"]; + node [fontname="Arial", fontsize=7, margin=0]; + edge [fontname="Arial", fontsize=11, penwidth=2.0, + arrowsize=1.2]; + + subgraph cluster_outer { + label="Buildroot-based Linux(R) Embedded Software for TI Devices"; + style="filled,bold"; + fillcolor="#F0F4FF"; + color="#1A237E"; + penwidth=4; + fontsize=20; + fontcolor="#1A237E"; + fontname="Arial Bold"; + + apps [ + shape=none, + label=< + + + + + + + + + + + + +
+ + ① Applications + +
+ + GUI Applications + + + + Custom Applications + +
+ + Trusted Applications + + + + Middleware and Libraries + +
+ > + ]; + + buildroot [ + shape=none, + label=< + + + + + + + + +
+ + ② Buildroot Build System + +
+ + Buildroot + + + + Buildroot External-TI + +
+ > + ]; + + tibsp [ + shape=none, + label=< + + + + + + + + + + + + + + + + + + + + + +
+ + ③ TI BSP Components + +
+ + Firmware and Security Components + +
+ + TF-A + + + + OP-TEE + + + + TI Linux Firmware +
+ + (N/A for AM62Lx-EVM) + + + 		+ + U-Boot + +
+ + Linux Kernel Components + +
+ + TI Linux Kernel + + + + TI Kernel Drivers + + + + Device Tree + +
+ > + ]; + + artifacts [ + shape=none, + label=< + + + + + + + + + +
+ + Build Artifacts + +
+ + SD Card Image + + + + Boot Artifacts + + + + Root Filesystem + +
+ > + ]; + + legend [ + shape=none, + label=< + + + + + + + + + + + + + + + + + + + + +
+ + Legend + +
+ + + + Applications Layer + +
+ + + + Buildroot Build System + +
+ + + + TI BSP Components + +
+ + + + Build Artifacts + +
+ > + ]; + } + + // Vertical flow: apps -> buildroot -> tibsp -> artifacts -> legend + apps -> buildroot [style=invis, weight=100]; + buildroot -> tibsp [style=invis, weight=100]; + tibsp -> artifacts [style=invis, weight=100]; + artifacts -> legend [style=invis, weight=100]; + + // Data-flow edges (constraint=false so they don't affect layout) + apps -> buildroot [ + color="#2E7D32", + penwidth=2.5, + arrowsize=1.2, + fontcolor="#2E7D32", + fontsize=11, + fontname="Arial Bold", + constraint=false + ]; + + tibsp -> buildroot [ + color="#4527A0", + penwidth=2.5, + arrowsize=1.2, + fontcolor="#4527A0", + fontsize=11, + fontname="Arial Bold", + constraint=false + ]; + + buildroot -> artifacts [ + color="#E65100", + penwidth=3.0, + arrowsize=1.5, + label=" Output ", + fontcolor="#E65100", + fontsize=11, + fontname="Arial Bold", + style=bold, + constraint=false + ]; +}