From 6509f50c69b26b88a77bcae6b9ba84c7e6122b73 Mon Sep 17 00:00:00 2001
From: Chris Lattner <sabre@nondot.org>
Date: Tue, 11 Oct 2011 23:01:39 +0000
Subject: [PATCH] improve some of the documentation around target data layout
 strings.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@141733 91177308-0d34-0410-b5e6-96231b3b80d8
---
 docs/LangRef.html                | 16 ++++++++++++++++
 include/llvm/Target/TargetData.h |  7 +++++++
 2 files changed, 23 insertions(+)

diff --git a/docs/LangRef.html b/docs/LangRef.html
index 145c19f3e5e..8e54f3c433a 100644
--- a/docs/LangRef.html
+++ b/docs/LangRef.html
@@ -1406,6 +1406,22 @@ target datalayout = "<i>layout specification</i>"
       implemented in terms of 64 &lt;2 x double&gt;, for example.</li>
 </ol>
 
+<p>The function of the data layout string may not be what you expect.  Notably,
+   this is not a specification from the frontend of what alignment the code
+   generator should use.</p>
+
+<p>Instead, if specified, the target data layout is required to match what the 
+   ultimate <em>code generator</em> expects.  This string is used by the 
+   mid-level optimizers to
+   improve code, and this only works if it matches what the ultimate code 
+   generator uses.  If you would like to generate IR that does not embed this
+   target-specific detail into the IR, then you don't have to specify the 
+   string.  This will disable some optimizations that require precise layout
+   information, but this also prevents those optimizations from introducing
+   target specificity into the IR.</p>
+
+
+
 </div>
 
 <!-- ======================================================================= -->
diff --git a/include/llvm/Target/TargetData.h b/include/llvm/Target/TargetData.h
index e34094ddb7b..26fd1870ac3 100644
--- a/include/llvm/Target/TargetData.h
+++ b/include/llvm/Target/TargetData.h
@@ -44,6 +44,7 @@ enum AlignTypeEnum {
   AGGREGATE_ALIGN = 'a',             ///< Aggregate alignment
   STACK_ALIGN = 's'                  ///< Stack objects alignment
 };
+  
 /// Target alignment element.
 ///
 /// Stores the alignment data associated with a given alignment type (pointer,
@@ -64,6 +65,12 @@ struct TargetAlignElem {
   bool operator==(const TargetAlignElem &rhs) const;
 };
 
+/// TargetData - This class holds a parsed version of the target data layout
+/// string in a module and provides methods for querying it.  The target data
+/// layout string is specified *by the target* - a frontend generating LLVM IR
+/// is required to generate the right target data for the target being codegen'd
+/// to.  If some measure of portability is desired, an empty string may be
+/// specified in the module.
 class TargetData : public ImmutablePass {
 private:
   bool          LittleEndian;          ///< Defaults to false
-- 
2.34.1