From b9d75a94dd617f0bcc4bd56c52e2d5e8a9bec3fa Mon Sep 17 00:00:00 2001 From: Bill Wendling Date: Sat, 11 Feb 2012 11:59:36 +0000 Subject: [PATCH] Document the new module flags. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@150301 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/LangRef.html | 126 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) diff --git a/docs/LangRef.html b/docs/LangRef.html index e3971ffed0d..074e91e684c 100644 --- a/docs/LangRef.html +++ b/docs/LangRef.html @@ -108,6 +108,10 @@ +
  • Module Flags Metadata +
      +
    +
  • Intrinsic Global Variables
    1. The 'llvm.used' Global Variable
      2. @@ -3029,6 +3033,128 @@ call void @llvm.dbg.value(metadata !24, i64 0, metadata !25) + +

      + Module Flags Metadata +

      + + +
      + +

      Information about the module as a whole is difficult to convey to LLVM's + subsystems. The LLVM IR isn't sufficient to transmit this + information. The llvm.module.flags named metadata exists in order to + facilitate this. These flags are in the form of key / value pairs — + much like a dictionary — making it easy for any subsystem who cares + about a flag to look it up.

      + +

      The llvm.module.flags metadata contains a list of metadata + triplets. Each triplet has the following form:

      + +
        +
      • The first element is a behavior flag, which specifies the behavior + when two (or more) modules are merged together, and it encounters two (or + more) metadata with the same ID. The supported behaviors are described + below.
        • + +
      • The second element is a metadata string that is a unique ID for the + metadata. How each ID is interpreted is documented below.
        • + +
      • The third element is the value of the flag.
        • +
      + +

      When two (or more) modules are merged together, the resulting + llvm.module.flags metadata is the union of the + modules' llvm.module.flags metadata. The only exception being a flag + with the Override behavior, which may override another flag's value + (see below).

      + +

      The following behaviors are supported:

      + + + + + + + + + + + + + + + + + + + + + + + + +
      ValueBehavior
      1 +
      Error
      +
      Emits an error if two values disagree. It is an error to have an ID + with both an Error and a Warning behavior.
      +
      2 +
      Warning
      +
      Emits a warning if two values disagree.
      +
      3 +
      Require
      +
      Emits an error when the specified value is not present or doesn't + have the specified value. It is an error for two (or more) + llvm.module.flags with the same ID to have the Require + behavior but different values. There may be multiple Require flags + per ID.
      +
      4 +
      Override
      +
      Uses the specified value if the two values disagree. It is an error + for two (or more) llvm.module.flags with the same ID to + have the Override behavior but different values.
      +
      + +

      An example of module flags:

      + +
      +!0 = metadata !{ i32 1, metadata !"foo", i32 1 }
+!1 = metadata !{ i32 4, metadata !"bar", i32 37 }
+!2 = metadata !{ i32 2, metadata !"qux", i32 42 }
+!3 = metadata !{ i32 3, metadata !"qux",
+  metadata !{
+    metadata !"foo", i32 1
+  }
+}
+!llvm.module.flags = !{ !0, !1, !2, !3 }
+
      + +
        +

      • Metadata !0 has the ID !"foo" and the value '1'. The + behavior if two or more !"foo" flags are seen is to emit an + error if their values are not equal.

        • + +

      • Metadata !1 has the ID !"bar" and the value '37'. The + behavior if two or more !"bar" flags are seen is to use the + value '37' if their values are not equal.

        • + +

      • Metadata !2 has the ID !"qux" and the value '42'. The + behavior if two or more !"qux" flags are seen is to emit a + warning if their values are not equal.

        • + +

      • Metadata !3 has the ID !"qux" and the value:

        + +
        +metadata !{ metadata !"foo", i32 1 }
+
        +

        The behavior is to emit an error if the llvm.module.flags does + not contain a flag with the ID !"foo" that has the value + '1'. If two or more !"qux" flags exist, then they must have + the same value or an error will be issued.

        • +
      + +
      +

      Intrinsic Global Variables