[openmp][docs] Describe how the internal components are found

[JonChesterfield]

Summary

Add a FAQ entry about the names of openmp offloading components
and how they are searched for.

[grokos]

LG, quite descriptive and covers everything related to OpenMP libraries. Waiting for others to comment as well.

[JonChesterfield]

Ping

[jhuber6]

The literals should go inside of an inline literal block (Two backticks).

[JonChesterfield]

I can't make phab print two ` next to each other but sure, happy to. Which strings do you have in mind? You're also very welcome to take over the diff and add quotes wherever looks appropriate, probably faster than writing a comment about it

[jhuber6]

openmp/docs/SupportAndFAQ.rst

167

I'd suggest anything like this that contains underscores or dashes. I'll leave it up to you if you want to put it around the library names as well.

198

[JonChesterfield]

• quote literals

[jhuber6]

LGTM, thanks.

[JonChesterfield]

Have gone with environment variables, library names, clang arguments and $ORIGIN. Also replaced -rpath with -Wl,-rpath as that's more explicitly a linker thing.

[JonChesterfield]

Thanks, landed.

openmp/docs/SupportAndFAQ.rst

 
 Some versions of the driver for the radeon vii (gfx906) will error unless the
 environment variable 'export HSA_IGNORE_SRAMECC_MISREPORT=1' is set.
 
 It is a recent addition to LLVM and the implementation differs from that which
 has been shipping in ROCm and AOMP for some time. Early adopters will encounter
 bugs.
 
+Q: What are the LLVM components used in offloading and how are they found?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The libraries used by an executable compiled for target offloading are:
+- ``libomp.so`` (or similar), the host openmp runtime
+- ``libomptarget.so``, the target-agnostic target offloading openmp runtime
+- plugins loaded by libomptarget.so:
+  - ``libomptarget.rtl.amdgpu.so``
+  - ``libomptarget.rtl.cuda.so``
+  - ``libomptarget.rtl.x86_64.so``
+  - ``libomptarget.rtl.ve.so``
+  - and others
+- dependencies of those plugins, e.g. cuda/rocr for nvptx/amdgpu
+
+The compiled executable is dynamically linked against a host runtime, e.g.
+``libomp.so``, and against the target offloading runtime, ``libomptarget.so``. These
+are found like any other dynamic library, by setting rpath or runpath on the
+executable, by setting ``LD_LIBRARY_PATH``, or by adding them to the system search.
+
+``libomptarget.so`` has rpath or runpath (whichever the system default is) set to
+``$ORIGIN``, and the plugins are located next to it, so it will find the plugins
+without any environment variables set. If ``LD_LIBRARY_PATH`` is set, whether it
+overrides which plugin is found depends on whether your system treats ``-Wl,-rpath``
+as RPATH or RUNPATH.
+
+The plugins will try to find their dependencies in plugin-dependent fashion.
+
+The cuda plugin is dynamically linked against libcuda if cmake found it at
+compiler build time. Otherwise it will attempt to dlopen ``libcuda.so``. It does
+not have rpath set.
+
+The amdgpu plugin is linked against ROCr if cmake found it at compiler build
+time. Otherwise it will attempt to dlopen ``libhsa-runtime64.so``. It has rpath
+set to ``$ORIGIN``, so installing ``libhsa-runtime64.so`` in the same directory is a
+way to locate it without environment variables.
+
+In addition to those, there is a compiler runtime library called deviceRTL.
+This is compiled from mostly common code into an architecture specific
+bitcode library, e.g. ``libomptarget-nvptx-sm_70.bc``.
+
+Clang and the deviceRTL need to match closely as the interface between them
+changes frequently. Using both from the same monorepo checkout is strongly
+recommended.
+
+Unlike the host side which lets environment variables select components, the
+deviceRTL that is located in the clang lib directory is preferred. Only if
+it is absent, the ``LIBRARY_PATH`` environment variable is searched to find a
+bitcode file with the right name. This can be overridden by passing a clang
+flag, ``--libomptarget-nvptx-bc-path`` or ``--libomptarget-amdgcn-bc-path``. That
+can specify a directory or an exact bitcode file to use.
+
+
 Q: Does OpenMP offloading support work in pre-packaged LLVM releases?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 For now, the answer is most likely *no*. Please see :ref:`build_offload_capable_compiler`.
 
 Q: Does OpenMP offloading support work in packages distributed as part of my OS?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 For now, the answer is most likely *no*. Please see :ref:`build_offload_capable_compiler`.