Re: [Mesa-dev] [RFC] gallium/docs: add some freedreno compiler docs
Acked-by: Brian Paul
On 01/29/2015 02:11 PM, Rob Clark wrote:
From: Rob Clark
Enable the 'sphinx.ext.graphviz' extension, and add in a section for
driver specific docs, with freedreno compiler docs beneath. The
goal is for more complete compiler docs, and hopefully some docs about
other parts of the driver (such as how tiling works, etc).
Note that there is also a Distribution -> Drivers section. Although
that appears to be simply just a list of drivers. Not sure if that
should move under the 'Drivers' section or left alone. I did add a
one-line section for freedreno in the existing Distribution -> Drivers
section.
Also, I'm not sure if there is a good way to link back to .rst source
files that live under the src/gallium/drivers/ directory, or if
that is even desired.
At least adding this under the existing gallium docs, versus my initial
approach which setup a new sphinx build docs tree under the freedreno
driver directory, results in a much smaller patch due to not having an
extra Makefile, conf.py, etc.
---
src/gallium/docs/source/conf.py| 2 +-
src/gallium/docs/source/distro.rst | 5 +
src/gallium/docs/source/drivers.rst| 9 +
src/gallium/docs/source/drivers/freedreno.rst | 9 +
.../docs/source/drivers/freedreno/ir3-notes.rst| 386 +
src/gallium/docs/source/index.rst | 1 +
6 files changed, 411 insertions(+), 1 deletion(-)
create mode 100644 src/gallium/docs/source/drivers.rst
create mode 100644 src/gallium/docs/source/drivers/freedreno.rst
create mode 100644 src/gallium/docs/source/drivers/freedreno/ir3-notes.rst
diff --git a/src/gallium/docs/source/conf.py b/src/gallium/docs/source/conf.py
index 1288666..5e8173d 100644
--- a/src/gallium/docs/source/conf.py
+++ b/src/gallium/docs/source/conf.py
@@ -22,7 +22,7 @@ sys.path.append(os.path.abspath('exts'))
# Add any Sphinx extension module names here, as strings. They can be
extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.pngmath', 'formatting']
+extensions = ['sphinx.ext.pngmath', 'sphinx.ext.graphviz', 'formatting']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
diff --git a/src/gallium/docs/source/distro.rst
b/src/gallium/docs/source/distro.rst
index d69c186..a841b34 100644
--- a/src/gallium/docs/source/distro.rst
+++ b/src/gallium/docs/source/distro.rst
@@ -60,6 +60,11 @@ AMD radeonsi
Driver for the AMD Southern Islands family of GPUs.
+freedreno
+^
+
+Driver for Qualcomm Adreno a2xx, a3xx, and a4xx series of GPUs.
+
.. _softpipe:
Softpipe
diff --git a/src/gallium/docs/source/drivers.rst
b/src/gallium/docs/source/drivers.rst
new file mode 100644
index 000..469197c
--- /dev/null
+++ b/src/gallium/docs/source/drivers.rst
@@ -0,0 +1,9 @@
+Drivers
+===
+
+Driver specific documentation.
+
+.. toctree::
+ :glob:
+
+ drivers/*
diff --git a/src/gallium/docs/source/drivers/freedreno.rst
b/src/gallium/docs/source/drivers/freedreno.rst
new file mode 100644
index 000..723ffdd
--- /dev/null
+++ b/src/gallium/docs/source/drivers/freedreno.rst
@@ -0,0 +1,9 @@
+Freedreno
+=
+
+Freedreno driver specific docs.
+
+.. toctree::
+ :glob:
+
+ freedreno/*
diff --git a/src/gallium/docs/source/drivers/freedreno/ir3-notes.rst
b/src/gallium/docs/source/drivers/freedreno/ir3-notes.rst
new file mode 100644
index 000..dd28700
--- /dev/null
+++ b/src/gallium/docs/source/drivers/freedreno/ir3-notes.rst
@@ -0,0 +1,386 @@
+IR3 NOTES
+=
+
+Some notes about ir3, the compiler and machine-specific IR for the shader ISA
introduced with adreno a3xx. The same shader ISA is present, with some small
differences, with adreno a4xx.
+
+Compared to the previous generation a2xx ISA (ir2), the a3xx ISA is a "simple"
scalar instruction set. However, the compiler is responsible, in most cases, to schedule
the instructions. The hardware does not try to hide the shader core pipeline stages.
For a common example, a common (cat2) ALU instruction takes four cycles, so a subsequent
cat2 instruction which uses the result must have three intervening instructions (or
nops). When operating on vec4's, typically the corresponding scalar instructions for
operating on the remaining three components could typically fit. Although that results
in a lot of edge cases where things fall over, like:
+
+::
+
+ ADD TEMP[0], TEMP[1], TEMP[2]
+ MUL TEMP[0], TEMP[1], TEMP[0].wzyx
+
+Here, the second instruction needs the output of the first group of scalar
instructions in the wrong order, resulting in not enough instruction spots
between the ``add r0.w, r1.w, r2.w`` and ``mul r0.x, r1.x, r0.w``. Which is
why the original/old compiler which merely translated nearly literally from
TGSI to ir3, had a strong tendency to fall over.
+
+So the current compiler instead, in the frontend, generates a
[Mesa-dev] [RFC] gallium/docs: add some freedreno compiler docs
From: Rob Clark
Enable the 'sphinx.ext.graphviz' extension, and add in a section for
driver specific docs, with freedreno compiler docs beneath. The
goal is for more complete compiler docs, and hopefully some docs about
other parts of the driver (such as how tiling works, etc).
Note that there is also a Distribution -> Drivers section. Although
that appears to be simply just a list of drivers. Not sure if that
should move under the 'Drivers' section or left alone. I did add a
one-line section for freedreno in the existing Distribution -> Drivers
section.
Also, I'm not sure if there is a good way to link back to .rst source
files that live under the src/gallium/drivers/ directory, or if
that is even desired.
At least adding this under the existing gallium docs, versus my initial
approach which setup a new sphinx build docs tree under the freedreno
driver directory, results in a much smaller patch due to not having an
extra Makefile, conf.py, etc.
---
src/gallium/docs/source/conf.py| 2 +-
src/gallium/docs/source/distro.rst | 5 +
src/gallium/docs/source/drivers.rst| 9 +
src/gallium/docs/source/drivers/freedreno.rst | 9 +
.../docs/source/drivers/freedreno/ir3-notes.rst| 386 +
src/gallium/docs/source/index.rst | 1 +
6 files changed, 411 insertions(+), 1 deletion(-)
create mode 100644 src/gallium/docs/source/drivers.rst
create mode 100644 src/gallium/docs/source/drivers/freedreno.rst
create mode 100644 src/gallium/docs/source/drivers/freedreno/ir3-notes.rst
diff --git a/src/gallium/docs/source/conf.py b/src/gallium/docs/source/conf.py
index 1288666..5e8173d 100644
--- a/src/gallium/docs/source/conf.py
+++ b/src/gallium/docs/source/conf.py
@@ -22,7 +22,7 @@ sys.path.append(os.path.abspath('exts'))
# Add any Sphinx extension module names here, as strings. They can be
extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.pngmath', 'formatting']
+extensions = ['sphinx.ext.pngmath', 'sphinx.ext.graphviz', 'formatting']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
diff --git a/src/gallium/docs/source/distro.rst
b/src/gallium/docs/source/distro.rst
index d69c186..a841b34 100644
--- a/src/gallium/docs/source/distro.rst
+++ b/src/gallium/docs/source/distro.rst
@@ -60,6 +60,11 @@ AMD radeonsi
Driver for the AMD Southern Islands family of GPUs.
+freedreno
+^
+
+Driver for Qualcomm Adreno a2xx, a3xx, and a4xx series of GPUs.
+
.. _softpipe:
Softpipe
diff --git a/src/gallium/docs/source/drivers.rst
b/src/gallium/docs/source/drivers.rst
new file mode 100644
index 000..469197c
--- /dev/null
+++ b/src/gallium/docs/source/drivers.rst
@@ -0,0 +1,9 @@
+Drivers
+===
+
+Driver specific documentation.
+
+.. toctree::
+ :glob:
+
+ drivers/*
diff --git a/src/gallium/docs/source/drivers/freedreno.rst
b/src/gallium/docs/source/drivers/freedreno.rst
new file mode 100644
index 000..723ffdd
--- /dev/null
+++ b/src/gallium/docs/source/drivers/freedreno.rst
@@ -0,0 +1,9 @@
+Freedreno
+=
+
+Freedreno driver specific docs.
+
+.. toctree::
+ :glob:
+
+ freedreno/*
diff --git a/src/gallium/docs/source/drivers/freedreno/ir3-notes.rst
b/src/gallium/docs/source/drivers/freedreno/ir3-notes.rst
new file mode 100644
index 000..dd28700
--- /dev/null
+++ b/src/gallium/docs/source/drivers/freedreno/ir3-notes.rst
@@ -0,0 +1,386 @@
+IR3 NOTES
+=
+
+Some notes about ir3, the compiler and machine-specific IR for the shader ISA
introduced with adreno a3xx. The same shader ISA is present, with some small
differences, with adreno a4xx.
+
+Compared to the previous generation a2xx ISA (ir2), the a3xx ISA is a "simple"
scalar instruction set. However, the compiler is responsible, in most cases,
to schedule the instructions. The hardware does not try to hide the shader
core pipeline stages. For a common example, a common (cat2) ALU instruction
takes four cycles, so a subsequent cat2 instruction which uses the result must
have three intervening instructions (or nops). When operating on vec4's,
typically the corresponding scalar instructions for operating on the remaining
three components could typically fit. Although that results in a lot of edge
cases where things fall over, like:
+
+::
+
+ ADD TEMP[0], TEMP[1], TEMP[2]
+ MUL TEMP[0], TEMP[1], TEMP[0].wzyx
+
+Here, the second instruction needs the output of the first group of scalar
instructions in the wrong order, resulting in not enough instruction spots
between the ``add r0.w, r1.w, r2.w`` and ``mul r0.x, r1.x, r0.w``. Which is
why the original/old compiler which merely translated nearly literally from
TGSI to ir3, had a strong tendency to fall over.
+
+So the current compiler instead, in the frontend, generates a
directed-acyclic-graph of instructions and basic blocks, which go through
