← Back to branch summary

~pali/+junk/llvm-toolchain-3.7

« back to all changes in this revision

Viewing changes to docs/HowToUseAttributes.rst

  • Committer: Package Import Robot
  • Author(s): Sylvestre Ledru
  • Date: 2015-07-15 17:51:08 UTC
  • Revision ID: package-import@ubuntu.com-20150715175108-l8mynwovkx4zx697
Tags: upstream-3.7~+rc2
Import upstream version 3.7~+rc2

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/HowToUseAttributes.rst
 
1
=====================
 
2
How To Use Attributes
 
3
=====================
 
4
 
 
5
.. contents::
 
6
  :local:
 
7
 
 
8
Introduction
 
9
============
 
10
 
 
11
Attributes in LLVM have changed in some fundamental ways.  It was necessary to
 
12
do this to support expanding the attributes to encompass more than a handful of
 
13
attributes --- e.g. command line options.  The old way of handling attributes
 
14
consisted of representing them as a bit mask of values.  This bit mask was
 
15
stored in a "list" structure that was reference counted.  The advantage of this
 
16
was that attributes could be manipulated with 'or's and 'and's.  The
 
17
disadvantage of this was that there was limited room for expansion, and
 
18
virtually no support for attribute-value pairs other than alignment.
 
19
 
 
20
In the new scheme, an ``Attribute`` object represents a single attribute that's
 
21
uniqued.  You use the ``Attribute::get`` methods to create a new ``Attribute``
 
22
object.  An attribute can be a single "enum" value (the enum being the
 
23
``Attribute::AttrKind`` enum), a string representing a target-dependent
 
24
attribute, 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
 
 
30
Note: for an attribute value pair, we expect a target-dependent attribute to
 
31
have a string for the value.
 
32
 
 
33
``Attribute``
 
34
=============
 
35
An ``Attribute`` object is designed to be passed around by value.
 
36
 
 
37
Because attributes are no longer represented as a bit mask, you will need to
 
38
convert any code which does treat them as a bit mask to use the new query
 
39
methods on the Attribute class.
 
40
 
 
41
``AttributeSet``
 
42
================
 
43
 
 
44
The ``AttributeSet`` class replaces the old ``AttributeList`` class.  The
 
45
``AttributeSet`` stores a collection of Attribute objects for each kind of
 
46
object that may have an attribute associated with it: the function as a
 
47
whole, the return type, or the function's parameters.  A function's attributes
 
48
are at index ``AttributeSet::FunctionIndex``; the return type's attributes are
 
49
at index ``AttributeSet::ReturnIndex``; and the function's parameters'
 
50
attributes are at indices 1, ..., n (where 'n' is the number of parameters).
 
51
Most methods on the ``AttributeSet`` class take an index parameter.
 
52
 
 
53
An ``AttributeSet`` is also a uniqued and immutable object.  You create an
 
54
``AttributeSet`` through the ``AttributeSet::get`` methods.  You can add and
 
55
remove attributes, which result in the creation of a new ``AttributeSet``.
 
56
 
 
57
An ``AttributeSet`` object is designed to be passed around by value.
 
58
 
 
59
Note: It is advised that you do *not* use the ``AttributeSet`` "introspection"
 
60
methods (e.g. ``Raw``, ``getRawPointer``, etc.).  These methods break
 
61
encapsulation, and may be removed in a future release (i.e. LLVM 4.0).
 
62
 
 
63
``AttrBuilder``
 
64
===============
 
65
 
 
66
Lastly, we have a "builder" class to help create the ``AttributeSet`` object
 
67
without having to create several different intermediate uniqued
 
68
``AttributeSet`` objects.  The ``AttrBuilder`` class allows you to add and
 
69
remove attributes at will.  The attributes won't be uniqued until you call the
 
70
appropriate ``AttributeSet::get`` method.
 
71
 
 
72
An ``AttrBuilder`` object is *not* designed to be passed around by value.  It
 
73
should be passed by reference.
 
74
 
 
75
Note: It is advised that you do *not* use the ``AttrBuilder::addRawValue()``
 
76
method or the ``AttrBuilder(uint64_t Val)`` constructor.  These are for
 
77
backwards compatibility and may be removed in a future release (i.e. LLVM 4.0).
 
78
 
 
79
And that's basically it! A lot of functionality is hidden behind these classes,
 
80
but the interfaces are pretty straight forward.
 
81