6 files changed, 139 insertions, 18 deletions
diff --git a/src/gallium/docs/source/conf.py b/src/gallium/docs/source/conf.py
index 99e665234e..0846e7d0ec 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', 'tgsi']
+extensions = ['sphinx.ext.pngmath', 'formatting']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
diff --git a/src/gallium/docs/source/debugging.rst b/src/gallium/docs/source/debugging.rst
new file mode 100644
index 0000000000..42bda5aee9
--- /dev/null
+++ b/src/gallium/docs/source/debugging.rst
@@ -0,0 +1,101 @@
+Debugging
+=========
+
+Debugging utilities in gallium.
+
+Debug Variables
+^^^^^^^^^^^^^^^
+
+All drivers respond to a set of common debug environment variables, as well as
+some driver-specific variables. Set them as normal environment variables for
+the platform or operating system you are running. For example, for Linux this
+can be done by typing "export var=value" into a console and then running the
+program from that console.
+
+Common
+""""""
+
+.. envvar:: GALLIUM_PRINT_OPTIONS <bool> (false)
+
+This option controls if the debug variables should be printed to stderr. This
+is probably the most useful variable, since it allows you to find which
+variables a driver uses.
+
+.. envvar:: GALLIUM_RBUG <bool> (false)
+
+Controls if the :ref:`rbug` should be used.
+
+.. envvar:: GALLIUM_TRACE <string> ("")
+
+If set, this variable will cause the :ref:`Trace` output to be written to the
+specified file. Paths may be relative or absolute; relative paths are relative
+to the working directory.  For example, setting it to "trace.xml" will cause
+the trace to be written to a file of the same name in the working directory.
+
+.. envvar:: GALLIUM_DUMP_CPU <bool> (false)
+
+Dump information about the current CPU that the driver is running on.
+
+.. envvar:: TGSI_PRINT_SANITY <bool> (false)
+
+Gallium has a built-in shader sanity checker.  This option controls whether
+the shader sanity checker prints its warnings and errors to stderr.
+
+.. envvar:: DRAW_USE_LLVM <bool> (false)
+
+Whether the :ref:`Draw` module will attempt to use LLVM for vertex and geometry shaders.
+
+
+State tracker-specific
+""""""""""""""""""""""
+
+.. envvar:: ST_DEBUG <flags> (0x0)
+
+Debug :ref:`flags` for the GL state tracker.
+
+
+Driver-specific
+"""""""""""""""
+
+.. envvar:: I915_DEBUG <flags> (0x0)
+
+Debug :ref:`flags` for the i915 driver.
+
+.. envvar:: I915_NO_HW <bool> (false)
+
+Stop the i915 driver from submitting commands to the hardware.
+
+.. envvar:: I915_DUMP_CMD <bool> (false)
+
+Dump all commands going to the hardware.
+
+.. envvar:: LP_DEBUG <flags> (0x0)
+
+Debug :ref:`flags` for the llvmpipe driver.
+
+.. envvar:: LP_NUM_THREADS <int> (number of CPUs)
+
+Number of threads that the llvmpipe driver should use.
+
+
+.. _flags:
+
+Flags
+"""""
+
+The variables of type "flags" all take a string with comma-separated flags to
+enable different debugging for different parts of the drivers or state
+tracker. If set to "help", the driver will print a list of flags which the
+variable accepts. Order does not matter.
+
+
+.. _rbug:
+
+Remote Debugger
+^^^^^^^^^^^^^^^
+
+The remote debugger, commonly known as rbug, allows for runtime inspections of
+:ref:`Context`, :ref:`Screen`, :ref:`Resource` and :ref:`Shader` objects; and
+pausing and stepping of :ref:`Draw` calls. Is used with rbug-gui which is
+hosted outside of the main mesa repository. rbug is can be used over a network
+connection, so the debugger does not need to be on the same machine.
diff --git a/src/gallium/docs/source/distro.rst b/src/gallium/docs/source/distro.rst
index e379ad3271..70d75b51e6 100644
--- a/src/gallium/docs/source/distro.rst
+++ b/src/gallium/docs/source/distro.rst
@@ -74,6 +74,11 @@ Trace
 Wrapper driver. Trace dumps an XML record of the calls made to the
 :ref:`Context` and :ref:`Screen` objects that it wraps.
 
+Rbug
+^^^^
+
+Wrapper driver. :ref:`rbug` driver used with stand alone rbug-gui.
+
 State Trackers
 --------------
 
diff --git a/src/gallium/docs/source/exts/formatting.py b/src/gallium/docs/source/exts/formatting.py
new file mode 100644
index 0000000000..14865f3603
--- /dev/null
+++ b/src/gallium/docs/source/exts/formatting.py
@@ -0,0 +1,31 @@
+# formatting.py
+# Sphinx extension providing formatting for Gallium-specific data
+# (c) Corbin Simpson 2010
+# Public domain to the extent permitted; contact author for special licensing
+
+import docutils.nodes
+import sphinx.addnodes
+
+def parse_envvar(env, sig, signode):
+    envvar, t, default = sig.split(" ", 2)
+    envvar = envvar.strip().upper()
+    t = " Type: %s" % t.strip(" <>").lower()
+    default = " Default: %s" % default.strip(" ()")
+    signode += sphinx.addnodes.desc_name(envvar, envvar)
+    signode += sphinx.addnodes.desc_type(t, t)
+    signode += sphinx.addnodes.desc_annotation(default, default)
+    return envvar
+
+def parse_opcode(env, sig, signode):
+    opcode, desc = sig.split("-", 1)
+    opcode = opcode.strip().upper()
+    desc = " (%s)" % desc.strip()
+    signode += sphinx.addnodes.desc_name(opcode, opcode)
+    signode += sphinx.addnodes.desc_annotation(desc, desc)
+    return opcode
+
+def setup(app):
+    app.add_description_unit("envvar", "envvar", "%s (environment variable)",
+        parse_envvar)
+    app.add_description_unit("opcode", "opcode", "%s (TGSI opcode)",
+        parse_opcode)
diff --git a/src/gallium/docs/source/exts/tgsi.py b/src/gallium/docs/source/exts/tgsi.py
deleted file mode 100644
index e92cd5c4d1..0000000000
--- a/src/gallium/docs/source/exts/tgsi.py
+++ /dev/null
@@ -1,17 +0,0 @@
-# tgsi.py
-# Sphinx extension providing formatting for TGSI opcodes
-# (c) Corbin Simpson 2010
-
-import docutils.nodes
-import sphinx.addnodes
-
-def parse_opcode(env, sig, signode):
-    opcode, desc = sig.split("-", 1)
-    opcode = opcode.strip().upper()
-    desc = " (%s)" % desc.strip()
-    signode += sphinx.addnodes.desc_name(opcode, opcode)
-    signode += sphinx.addnodes.desc_annotation(desc, desc)
-    return opcode
-
-def setup(app):
-    app.add_description_unit("opcode", "opcode", "%s (TGSI opcode)", parse_opcode)
diff --git a/src/gallium/docs/source/index.rst b/src/gallium/docs/source/index.rst
index 54bc883fce..6c19842dac 100644
--- a/src/gallium/docs/source/index.rst
+++ b/src/gallium/docs/source/index.rst
@@ -12,6 +12,7 @@ Contents:
    :maxdepth: 2
 
    intro
+   debugging
    tgsi
    screen
    context