81 lines · plain
1=====================2How To Use Attributes3=====================4 5.. contents::6 :local:7 8Introduction9============10 11Attributes in LLVM have changed in some fundamental ways. It was necessary to12do this to support expanding the attributes to encompass more than a handful of13attributes --- e.g. command line options. The old way of handling attributes14consisted of representing them as a bit mask of values. This bit mask was15stored in a "list" structure that was reference counted. The advantage of this16was that attributes could be manipulated with 'or's and 'and's. The17disadvantage of this was that there was limited room for expansion, and18virtually no support for attribute-value pairs other than alignment.19 20In the new scheme, an ``Attribute`` object represents a single attribute that's21uniqued. You use the ``Attribute::get`` methods to create a new ``Attribute``22object. An attribute can be a single "enum" value (the enum being the23``Attribute::AttrKind`` enum), a string representing a target-dependent24attribute, or an attribute-value pair. Some examples:25 26* Target-independent: ``noinline``, ``zext``27* Target-dependent: ``"no-sse"``, ``"thumb2"``28* Attribute-value pair: ``"cpu" = "cortex-a8"``, ``align = 4``29 30Note: for an attribute value pair, we expect a target-dependent attribute to31have a string for the value.32 33``Attribute``34=============35An ``Attribute`` object is designed to be passed around by value.36 37Because attributes are no longer represented as a bit mask, you will need to38convert any code which does treat them as a bit mask to use the new query39methods on the Attribute class.40 41``AttributeList``42=================43 44The ``AttributeList`` stores a collection of Attribute objects for each kind of45object that may have an attribute associated with it: the function as a whole,46the return type, or the function's parameters. A function's attributes are at47index ``AttributeList::FunctionIndex``; the return type's attributes are at48index ``AttributeList::ReturnIndex``; and the function's parameters' attributes49are at indices 1, ..., n (where 'n' is the number of parameters). Most methods50on the ``AttributeList`` class take an index parameter.51 52An ``AttributeList`` is also a uniqued and immutable object. You create an53``AttributeList`` through the ``AttributeList::get`` methods. You can add and54remove attributes, which result in the creation of a new ``AttributeList``.55 56An ``AttributeList`` object is designed to be passed around by value.57 58Note: It is advised that you do *not* use the ``AttributeList`` "introspection"59methods (e.g. ``Raw``, ``getRawPointer``, etc.). These methods break60encapsulation, and may be removed in a future release.61 62``AttrBuilder``63===============64 65Lastly, we have a "builder" class to help create the ``AttributeList`` object66without having to create several different intermediate uniqued67``AttributeList`` objects. The ``AttrBuilder`` class allows you to add and68remove attributes at will. The attributes won't be uniqued until you call the69appropriate ``AttributeList::get`` method.70 71An ``AttrBuilder`` object is *not* designed to be passed around by value. It72should be passed by reference.73 74Note: It is advised that you do *not* use the ``AttrBuilder::addRawValue()``75method or the ``AttrBuilder(uint64_t Val)`` constructor. These are for76backwards compatibility and may be removed in a future release.77 78And that's basically it! A lot of functionality is hidden behind these classes,79but the interfaces are pretty straight forward.80 81