From: Erik Faye-Lund Date: Tue, 30 Jun 2020 11:01:04 +0000 (+0200) Subject: docs: move gallium specific docs into gallium folder X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=892fdde23f44df78391eb0ff50ef031c8b978384;p=mesa.git docs: move gallium specific docs into gallium folder Reviewed-by: Eric Engestrom Part-of: --- diff --git a/docs/_exts/redirects.py b/docs/_exts/redirects.py index 4eb7b855b58..af53f7f4fde 100644 --- a/docs/_exts/redirects.py +++ b/docs/_exts/redirects.py @@ -1,6 +1,9 @@ import os -redirects = [] +redirects = [ + ('llvmpipe', 'gallium/drivers/llvmpipe'), + ('postprocess', 'gallium/postprocess') +] def create_redirect(dst): tpl = '' diff --git a/docs/contents.rst b/docs/contents.rst index 67246e3e014..4403bc0898d 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -44,9 +44,7 @@ debugging perf extensions - llvmpipe vmware-guest - postprocess application-issues viewperf xlibdriver diff --git a/docs/gallium/drivers/llvmpipe.rst b/docs/gallium/drivers/llvmpipe.rst new file mode 100644 index 00000000000..ec8e92dc0a8 --- /dev/null +++ b/docs/gallium/drivers/llvmpipe.rst @@ -0,0 +1,284 @@ +Gallium LLVMpipe Driver +======================= + +Introduction +------------ + +The Gallium llvmpipe driver is a software rasterizer that uses LLVM to +do runtime code generation. Shaders, point/line/triangle rasterization +and vertex processing are implemented with LLVM IR which is translated +to x86, x86-64, or ppc64le machine code. Also, the driver is +multithreaded to take advantage of multiple CPU cores (up to 8 at this +time). It's the fastest software rasterizer for Mesa. + +Requirements +------------ + +- For x86 or amd64 processors, 64-bit mode is recommended. Support for + SSE2 is strongly encouraged. Support for SSE3 and SSE4.1 will yield + the most efficient code. The fewer features the CPU has the more + likely it is that you will run into underperforming, buggy, or + incomplete code. + + For ppc64le processors, use of the Altivec feature (the Vector + Facility) is recommended if supported; use of the VSX feature (the + Vector-Scalar Facility) is recommended if supported AND Mesa is built + with LLVM version 4.0 or later. + + See ``/proc/cpuinfo`` to know what your CPU supports. + +- Unless otherwise stated, LLVM version 3.4 is recommended; 3.3 or + later is required. + + For Linux, on a recent Debian based distribution do: + + .. code-block:: console + + aptitude install llvm-dev + + If you want development snapshot builds of LLVM for Debian and + derived distributions like Ubuntu, you can use the APT repository at + `apt.llvm.org `__, which are maintained by + Debian's LLVM maintainer. + + For a RPM-based distribution do: + + .. code-block:: console + + yum install llvm-devel + + For Windows you will need to build LLVM from source with MSVC or + MINGW (either natively or through cross compilers) and CMake, and set + the ``LLVM`` environment variable to the directory you installed it + to. LLVM will be statically linked, so when building on MSVC it needs + to be built with a matching CRT as Mesa, and you'll need to pass + ``-DLLVM_USE_CRT_xxx=yyy`` as described below. + + + +-----------------+----------------------------------------------------------------+ + | LLVM build-type | Mesa build-type | + | +--------------------------------+-------------------------------+ + | | debug,checked | release,profile | + +=================+================================+===============================+ + | Debug | ``-DLLVM_USE_CRT_DEBUG=MTd`` | ``-DLLVM_USE_CRT_DEBUG=MT`` | + +-----------------+--------------------------------+-------------------------------+ + | Release | ``-DLLVM_USE_CRT_RELEASE=MTd`` | ``-DLLVM_USE_CRT_RELEASE=MT`` | + +-----------------+--------------------------------+-------------------------------+ + + You can build only the x86 target by passing + ``-DLLVM_TARGETS_TO_BUILD=X86`` to cmake. + +- scons (optional) + +Building +-------- + +To build everything on Linux invoke scons as: + +.. code-block:: console + + scons build=debug libgl-xlib + +Alternatively, you can build it with meson with: + +.. code-block:: console + + mkdir build + cd build + meson -D glx=gallium-xlib -D gallium-drivers=swrast + ninja + +but the rest of these instructions assume that scons is used. For +Windows the procedure is similar except the target: + +.. code-block:: console + + scons platform=windows build=debug libgl-gdi + +Using +----- + +Linux +~~~~~ + +On Linux, building will create a drop-in alternative for ``libGL.so`` +into + +:: + + build/foo/gallium/targets/libgl-xlib/libGL.so + +or + +:: + + lib/gallium/libGL.so + +To use it set the ``LD_LIBRARY_PATH`` environment variable accordingly. + +For performance evaluation pass ``build=release`` to scons, and use the +corresponding lib directory without the ``-debug`` suffix. + +Windows +~~~~~~~ + +On Windows, building will create +``build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll`` which +is a drop-in alternative for system's ``opengl32.dll``. To use it put it +in the same directory as your application. It can also be used by +replacing the native ICD driver, but it's quite an advanced usage, so if +you need to ask, don't even try it. + +There is however an easy way to replace the OpenGL software renderer +that comes with Microsoft Windows 7 (or later) with llvmpipe (that is, +on systems without any OpenGL drivers): + +- copy + ``build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll`` to + ``C:\Windows\SysWOW64\mesadrv.dll`` + +- load this registry settings: + + :: + + REGEDIT4 + + ; https://technet.microsoft.com/en-us/library/cc749368.aspx + ; https://www.msfn.org/board/topic/143241-portable-windows-7-build-from-winpe-30/page-5#entry942596 + [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\OpenGLDrivers\MSOGL] + "DLL"="mesadrv.dll" + "DriverVersion"=dword:00000001 + "Flags"=dword:00000001 + "Version"=dword:00000002 + +- Ditto for 64 bits drivers if you need them. + +Profiling +--------- + +To profile llvmpipe you should build as + +:: + + scons build=profile + +This will ensure that frame pointers are used both in C and JIT +functions, and that no tail call optimizations are done by gcc. + +Linux perf integration +~~~~~~~~~~~~~~~~~~~~~~ + +On Linux, it is possible to have symbol resolution of JIT code with +`Linux perf `__: + +:: + + perf record -g /my/application + perf report + +When run inside Linux perf, llvmpipe will create a +``/tmp/perf-XXXXX.map`` file with symbol address table. It also dumps +assembly code to ``/tmp/perf-XXXXX.map.asm``, which can be used by the +``bin/perf-annotate-jit.py`` script to produce disassembly of the +generated code annotated with the samples. + +You can obtain a call graph via +`Gprof2Dot `__. + +Unit testing +------------ + +Building will also create several unit tests in +``build/linux-???-debug/gallium/drivers/llvmpipe``: + +- ``lp_test_blend``: blending +- ``lp_test_conv``: SIMD vector conversion +- ``lp_test_format``: pixel unpacking/packing + +Some of these tests can output results and benchmarks to a tab-separated +file for later analysis, e.g.: + +:: + + build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv + +Development Notes +----------------- + +- When looking at this code for the first time, start in lp_state_fs.c, + and then skim through the ``lp_bld_*`` functions called there, and + the comments at the top of the ``lp_bld_*.c`` functions. +- The driver-independent parts of the LLVM / Gallium code are found in + ``src/gallium/auxiliary/gallivm/``. The filenames and function + prefixes need to be renamed from ``lp_bld_`` to something else + though. +- We use LLVM-C bindings for now. They are not documented, but follow + the C++ interfaces very closely, and appear to be complete enough for + code generation. See `this stand-alone + example `__. + See the ``llvm-c/Core.h`` file for reference. + +.. _recommended_reading: + +Recommended Reading +------------------- + +- Rasterization + + - `Triangle Scan Conversion using 2D Homogeneous + Coordinates `__ + - `Rasterization on + Larrabee `__ + (`DevMaster + copy `__) + - `Rasterization using half-space + functions `__ + - `Advanced + Rasterization `__ + - `Optimizing Software Occlusion + Culling `__ + +- Texture sampling + + - `Perspective Texture + Mapping `__ + - `Texturing As In + Unreal `__ + - `Run-Time MIP-Map + Filtering `__ + - `Will "brilinear" filtering + persist? `__ + - `Trilinear + filtering `__ + - `Texture + Swizzling `__ + +- SIMD + + - `Whole-Function + Vectorization `__ + +- Optimization + + - `Optimizing Pixomatic For Modern x86 + Processors `__ + - `Intel 64 and IA-32 Architectures Optimization Reference + Manual `__ + - `Software optimization + resources `__ + - `Intel Intrinsics + Guide `__ + +- LLVM + + - `LLVM Language Reference + Manual `__ + - `The secret of LLVM C + bindings `__ + +- General + + - `A trip through the Graphics + Pipeline `__ + - `WARP Architecture and + Performance `__ diff --git a/docs/gallium/index.rst b/docs/gallium/index.rst index 9688afb2215..29fbefa2eb5 100644 --- a/docs/gallium/index.rst +++ b/docs/gallium/index.rst @@ -16,6 +16,7 @@ Contents: cso distro drivers + postprocess glossary Indices and tables diff --git a/docs/gallium/postprocess.rst b/docs/gallium/postprocess.rst new file mode 100644 index 00000000000..276f3863756 --- /dev/null +++ b/docs/gallium/postprocess.rst @@ -0,0 +1,33 @@ +Gallium Post-processing +======================= + +The Gallium drivers support user-defined image post-processing. At the +end of drawing a frame a post-processing filter can be applied to the +rendered image. Example filters include morphological antialiasing and +cell shading. + +The filters can be toggled per-app via driconf, or per-session via the +corresponding environment variables. + +Multiple filters can be used together. + +PP environment variables +------------------------ + +- PP_DEBUG - If defined debug information will be printed to stderr. + +Current filters +--------------- + +- pp_nored, pp_nogreen, pp_noblue - set to 1 to remove the + corresponding color channel. These are basic filters for easy testing + of the PP queue. +- pp_jimenezmlaa, pp_jimenezmlaa_color - `Jimenez's + MLAA `__ is a morphological + antialiasing filter. The two versions use depth and color data, + respectively. Which works better depends on the app - depth will not + blur text, but it will miss transparent textures for example. Set to + a number from 2 to 32, roughly corresponding to quality. Numbers + higher than 8 see minimizing gains. +- pp_celshade - set to 1 to enable cell shading (a more complex color + filter). diff --git a/docs/llvmpipe.rst b/docs/llvmpipe.rst deleted file mode 100644 index ec8e92dc0a8..00000000000 --- a/docs/llvmpipe.rst +++ /dev/null @@ -1,284 +0,0 @@ -Gallium LLVMpipe Driver -======================= - -Introduction ------------- - -The Gallium llvmpipe driver is a software rasterizer that uses LLVM to -do runtime code generation. Shaders, point/line/triangle rasterization -and vertex processing are implemented with LLVM IR which is translated -to x86, x86-64, or ppc64le machine code. Also, the driver is -multithreaded to take advantage of multiple CPU cores (up to 8 at this -time). It's the fastest software rasterizer for Mesa. - -Requirements ------------- - -- For x86 or amd64 processors, 64-bit mode is recommended. Support for - SSE2 is strongly encouraged. Support for SSE3 and SSE4.1 will yield - the most efficient code. The fewer features the CPU has the more - likely it is that you will run into underperforming, buggy, or - incomplete code. - - For ppc64le processors, use of the Altivec feature (the Vector - Facility) is recommended if supported; use of the VSX feature (the - Vector-Scalar Facility) is recommended if supported AND Mesa is built - with LLVM version 4.0 or later. - - See ``/proc/cpuinfo`` to know what your CPU supports. - -- Unless otherwise stated, LLVM version 3.4 is recommended; 3.3 or - later is required. - - For Linux, on a recent Debian based distribution do: - - .. code-block:: console - - aptitude install llvm-dev - - If you want development snapshot builds of LLVM for Debian and - derived distributions like Ubuntu, you can use the APT repository at - `apt.llvm.org `__, which are maintained by - Debian's LLVM maintainer. - - For a RPM-based distribution do: - - .. code-block:: console - - yum install llvm-devel - - For Windows you will need to build LLVM from source with MSVC or - MINGW (either natively or through cross compilers) and CMake, and set - the ``LLVM`` environment variable to the directory you installed it - to. LLVM will be statically linked, so when building on MSVC it needs - to be built with a matching CRT as Mesa, and you'll need to pass - ``-DLLVM_USE_CRT_xxx=yyy`` as described below. - - - +-----------------+----------------------------------------------------------------+ - | LLVM build-type | Mesa build-type | - | +--------------------------------+-------------------------------+ - | | debug,checked | release,profile | - +=================+================================+===============================+ - | Debug | ``-DLLVM_USE_CRT_DEBUG=MTd`` | ``-DLLVM_USE_CRT_DEBUG=MT`` | - +-----------------+--------------------------------+-------------------------------+ - | Release | ``-DLLVM_USE_CRT_RELEASE=MTd`` | ``-DLLVM_USE_CRT_RELEASE=MT`` | - +-----------------+--------------------------------+-------------------------------+ - - You can build only the x86 target by passing - ``-DLLVM_TARGETS_TO_BUILD=X86`` to cmake. - -- scons (optional) - -Building --------- - -To build everything on Linux invoke scons as: - -.. code-block:: console - - scons build=debug libgl-xlib - -Alternatively, you can build it with meson with: - -.. code-block:: console - - mkdir build - cd build - meson -D glx=gallium-xlib -D gallium-drivers=swrast - ninja - -but the rest of these instructions assume that scons is used. For -Windows the procedure is similar except the target: - -.. code-block:: console - - scons platform=windows build=debug libgl-gdi - -Using ------ - -Linux -~~~~~ - -On Linux, building will create a drop-in alternative for ``libGL.so`` -into - -:: - - build/foo/gallium/targets/libgl-xlib/libGL.so - -or - -:: - - lib/gallium/libGL.so - -To use it set the ``LD_LIBRARY_PATH`` environment variable accordingly. - -For performance evaluation pass ``build=release`` to scons, and use the -corresponding lib directory without the ``-debug`` suffix. - -Windows -~~~~~~~ - -On Windows, building will create -``build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll`` which -is a drop-in alternative for system's ``opengl32.dll``. To use it put it -in the same directory as your application. It can also be used by -replacing the native ICD driver, but it's quite an advanced usage, so if -you need to ask, don't even try it. - -There is however an easy way to replace the OpenGL software renderer -that comes with Microsoft Windows 7 (or later) with llvmpipe (that is, -on systems without any OpenGL drivers): - -- copy - ``build/windows-x86-debug/gallium/targets/libgl-gdi/opengl32.dll`` to - ``C:\Windows\SysWOW64\mesadrv.dll`` - -- load this registry settings: - - :: - - REGEDIT4 - - ; https://technet.microsoft.com/en-us/library/cc749368.aspx - ; https://www.msfn.org/board/topic/143241-portable-windows-7-build-from-winpe-30/page-5#entry942596 - [HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\OpenGLDrivers\MSOGL] - "DLL"="mesadrv.dll" - "DriverVersion"=dword:00000001 - "Flags"=dword:00000001 - "Version"=dword:00000002 - -- Ditto for 64 bits drivers if you need them. - -Profiling ---------- - -To profile llvmpipe you should build as - -:: - - scons build=profile - -This will ensure that frame pointers are used both in C and JIT -functions, and that no tail call optimizations are done by gcc. - -Linux perf integration -~~~~~~~~~~~~~~~~~~~~~~ - -On Linux, it is possible to have symbol resolution of JIT code with -`Linux perf `__: - -:: - - perf record -g /my/application - perf report - -When run inside Linux perf, llvmpipe will create a -``/tmp/perf-XXXXX.map`` file with symbol address table. It also dumps -assembly code to ``/tmp/perf-XXXXX.map.asm``, which can be used by the -``bin/perf-annotate-jit.py`` script to produce disassembly of the -generated code annotated with the samples. - -You can obtain a call graph via -`Gprof2Dot `__. - -Unit testing ------------- - -Building will also create several unit tests in -``build/linux-???-debug/gallium/drivers/llvmpipe``: - -- ``lp_test_blend``: blending -- ``lp_test_conv``: SIMD vector conversion -- ``lp_test_format``: pixel unpacking/packing - -Some of these tests can output results and benchmarks to a tab-separated -file for later analysis, e.g.: - -:: - - build/linux-x86_64-debug/gallium/drivers/llvmpipe/lp_test_blend -o blend.tsv - -Development Notes ------------------ - -- When looking at this code for the first time, start in lp_state_fs.c, - and then skim through the ``lp_bld_*`` functions called there, and - the comments at the top of the ``lp_bld_*.c`` functions. -- The driver-independent parts of the LLVM / Gallium code are found in - ``src/gallium/auxiliary/gallivm/``. The filenames and function - prefixes need to be renamed from ``lp_bld_`` to something else - though. -- We use LLVM-C bindings for now. They are not documented, but follow - the C++ interfaces very closely, and appear to be complete enough for - code generation. See `this stand-alone - example `__. - See the ``llvm-c/Core.h`` file for reference. - -.. _recommended_reading: - -Recommended Reading -------------------- - -- Rasterization - - - `Triangle Scan Conversion using 2D Homogeneous - Coordinates `__ - - `Rasterization on - Larrabee `__ - (`DevMaster - copy `__) - - `Rasterization using half-space - functions `__ - - `Advanced - Rasterization `__ - - `Optimizing Software Occlusion - Culling `__ - -- Texture sampling - - - `Perspective Texture - Mapping `__ - - `Texturing As In - Unreal `__ - - `Run-Time MIP-Map - Filtering `__ - - `Will "brilinear" filtering - persist? `__ - - `Trilinear - filtering `__ - - `Texture - Swizzling `__ - -- SIMD - - - `Whole-Function - Vectorization `__ - -- Optimization - - - `Optimizing Pixomatic For Modern x86 - Processors `__ - - `Intel 64 and IA-32 Architectures Optimization Reference - Manual `__ - - `Software optimization - resources `__ - - `Intel Intrinsics - Guide `__ - -- LLVM - - - `LLVM Language Reference - Manual `__ - - `The secret of LLVM C - bindings `__ - -- General - - - `A trip through the Graphics - Pipeline `__ - - `WARP Architecture and - Performance `__ diff --git a/docs/postprocess.rst b/docs/postprocess.rst deleted file mode 100644 index 276f3863756..00000000000 --- a/docs/postprocess.rst +++ /dev/null @@ -1,33 +0,0 @@ -Gallium Post-processing -======================= - -The Gallium drivers support user-defined image post-processing. At the -end of drawing a frame a post-processing filter can be applied to the -rendered image. Example filters include morphological antialiasing and -cell shading. - -The filters can be toggled per-app via driconf, or per-session via the -corresponding environment variables. - -Multiple filters can be used together. - -PP environment variables ------------------------- - -- PP_DEBUG - If defined debug information will be printed to stderr. - -Current filters ---------------- - -- pp_nored, pp_nogreen, pp_noblue - set to 1 to remove the - corresponding color channel. These are basic filters for easy testing - of the PP queue. -- pp_jimenezmlaa, pp_jimenezmlaa_color - `Jimenez's - MLAA `__ is a morphological - antialiasing filter. The two versions use depth and color data, - respectively. Which works better depends on the app - depth will not - blur text, but it will miss transparent textures for example. Set to - a number from 2 to 32, roughly corresponding to quality. Numbers - higher than 8 see minimizing gains. -- pp_celshade - set to 1 to enable cell shading (a more complex color - filter). diff --git a/docs/systems.rst b/docs/systems.rst index b4f7d84191a..334a7667f9d 100644 --- a/docs/systems.rst +++ b/docs/systems.rst @@ -31,7 +31,7 @@ Hardware drivers include: Software drivers include: -- :doc:`llvmpipe ` - uses LLVM for x86 JIT code generation +- :doc:`llvmpipe ` - uses LLVM for x86 JIT code generation and is multi-threaded - softpipe - a reference Gallium driver - :doc:`svga ` - driver for vmware virtual gpu