Adding a HowTo for Attributes.

This is based on Bill Wendling's email.  No additional content has been added,
but now there's a place for Attributes to capture future information.

llvm-svn: 174961

llvm/docs/HowToUseAttributes.rst

@@ -0,0 +1,80 @@
+==============================================
+How To Use Attributes
+==============================================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+Attributes in LLVM have changed in some fundamental ways. It was necessary to do
+this to support expanding the attributes to encompass more than a handful of
+attributes --- e.g. command line options. The old way of handling attributes
+consisted of representing them as a bit mask of values. This bit mask was stored
+in a "list" structure that was reference counted. The advantage of this was that
+attributes could be manipulated with 'or's and 'and's. The disadvantage of this
+was that there was limited room for expansion, and virtually no support for
+attribute-value pairs other than alignment.
+
+In the new scheme, an Attribute object represents a single attribute that's
+uniqued. You use the "Attribute::get" methods to create a new Attribute
+object. An attribute can be a single "enum" value (the enum being the
+Attribute::AttrKind enum), a string representing a target-dependent attribute,
+or an attribute-value pair. Some examples:
+
+* Target-independent:   noinline, zext
+* Target-dependent:     "no-sse", "thumb2"
+* Attribute-value pair: "cpu" = "cortex-a8", align = 4
+
+Note: for an attribute value pair, we expect a target-dependent attribute to
+have a string for the value.
+
+Attribute
+=========
+An Attribute object is designed to be passed around by value.
+
+Because attributes are no longer represented as a bit mask, you will need to
+convert any code which does treat them as a bit mask to use the new query
+methods on the Attribute class.
+
+AttributeSet
+============
+
+The next class is the AttributeSet class. This replaces the old AttributeList
+class. The AttributeSet stores a collection of Attribute objects for each kind
+of object that may have an attribute associated with it: the function as a
+whole, the return type, or the function's parameters. A function's attributes
+are at index "AttributeSet::FunctionIndex"; the return type's attributes are at
+index "AttributeSet::ReturnIndex"; and the function's parameters' attributes are
+at indices 1, ..., n (where 'n' is the number of parameters). Most methods on
+the AttributeSet class take an index parameter.
+
+An AttributeSet is also a uniqued and immutable object. You create an
+AttributeSet through the "AttributeSet::get" methods. You can add and remove
+attributes, which result in the creation of a new AttributeSet.
+
+An AttributeSet object is designed to be passed around by value.
+
+Note: It is advised that you do *not* use the AttributeSet "Introspection"
+methods (e.g. 'Raw', 'getRawPointer', etc.). These methods break encapsulation,
+and may be removed in a future release (i.e. 4.0).
+
+AttrBuilder
+================
+
+Lastly, we have a 'builder' class to help create the AttributeSet object without
+having to create several different intermediate uniqued AttributeSet
+objects. The AttrBuilder class allows you to add and remove attributes at
+will. The attributes won't be uniqued until you call the appropriate
+"AttributeSet::get" method.
+
+An AttrBuilder object is *not* designed to be passed around by value. It should
+be passed by reference.
+
+Note: It is advised that you do *not* use the "AttrBuilder::addRawValue()"
+method or the "AttrBuilder(uint64_t Val)" c'tor. These are for backwards
+compatibility and may be removed in a future release (i.e. 4.0).
+
+And that's basically it! A lot of functionality is hidden behind these classes,
+but the interfaces are pretty straight forward.

llvm/docs/index.rst

@@ -247,6 +247,7 @@ For API clients and LLVM developers.
    GarbageCollection
    WritingAnLLVMPass
    TableGen/LangRef
+   HowToUseAttributes
 
 :doc:`WritingAnLLVMPass`
    Information on how to write LLVM transformations and analyses.
@@ -312,6 +313,8 @@ For API clients and LLVM developers.
 :doc:`MarkedUpDisassembly`
    This document describes the optional rich disassembly output syntax.
 
+:doc:`HowToUseAttributes`
+  Answers some questions about the new Attributes infrastructure.
 
 Development Process Documentation
 =================================