improve some of the documentation around target data layout strings.

llvm-svn: 141733

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>
 
 <!-- ======================================================================= -->

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