| ===================== |
| 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. |
| |
| ``AttributeList`` |
| ================= |
| |
| The ``AttributeList`` 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 ``AttributeList::FunctionIndex``; the return type's attributes are at |
| index ``AttributeList::ReturnIndex``; and the function's parameters' attributes |
| are at indices 1, ..., n (where 'n' is the number of parameters). Most methods |
| on the ``AttributeList`` class take an index parameter. |
| |
| An ``AttributeList`` is also a uniqued and immutable object. You create an |
| ``AttributeList`` through the ``AttributeList::get`` methods. You can add and |
| remove attributes, which result in the creation of a new ``AttributeList``. |
| |
| An ``AttributeList`` object is designed to be passed around by value. |
| |
| Note: It is advised that you do *not* use the ``AttributeList`` "introspection" |
| methods (e.g. ``Raw``, ``getRawPointer``, etc.). These methods break |
| encapsulation, and may be removed in a future release (i.e. LLVM 4.0). |
| |
| ``AttrBuilder`` |
| =============== |
| |
| Lastly, we have a "builder" class to help create the ``AttributeList`` object |
| without having to create several different intermediate uniqued |
| ``AttributeList`` objects. The ``AttrBuilder`` class allows you to add and |
| remove attributes at will. The attributes won't be uniqued until you call the |
| appropriate ``AttributeList::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)`` constructor. These are for |
| backwards compatibility and may be removed in a future release (i.e. LLVM 4.0). |
| |
| And that's basically it! A lot of functionality is hidden behind these classes, |
| but the interfaces are pretty straight forward. |
| |
