diff options
Diffstat (limited to 'src/gallium/docs/source')
| -rw-r--r-- | src/gallium/docs/source/conf.py | 2 | ||||
| -rw-r--r-- | src/gallium/docs/source/debugging.rst | 101 | ||||
| -rw-r--r-- | src/gallium/docs/source/distro.rst | 5 | ||||
| -rw-r--r-- | src/gallium/docs/source/exts/formatting.py | 31 | ||||
| -rw-r--r-- | src/gallium/docs/source/exts/tgsi.py | 17 | ||||
| -rw-r--r-- | src/gallium/docs/source/index.rst | 1 |
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 |