[llvm] XCOFF associated metadata (PR #159096)

[Wael Yehia via llvm-commits]

================
@@ -8440,6 +8440,35 @@ Example:
 The ``nofree`` metadata indicates the memory pointed by the pointer will not be
 freed after the attached instruction.
 
+'``ref``' Metadata
+^^^^^^^^^^^^^^^^^^
+
+The ``ref`` metadata may be attached to a global variable definition with a
+single argument that references a global object. The metadata is lowered to a
+.ref directive which will emit a relocation introducing an explicit dependence
+to the referenced symbol. This is typically used when there is some implicit
+dependence between the symbols that is otherwise opaque to the linker. One such
+example is metadata which is accessed by a runtime with associated
----------------
w2yehia wrote:

the term metadata is vague, maybe say:
One such example is "metadata" variables, associated to a function, that are accessed by a runtime via __start_<section_name> and __stop_<section_name> symbols. The function would have a `!ref` MD referencing the variables.

https://github.com/llvm/llvm-project/pull/159096