llvm.org GIT mirror llvm / 0013a5d
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. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@174961 91177308-0d34-0410-b5e6-96231b3b80d8 Joe Abbey 6 years ago
2 changed file(s) with 83 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
0 ==============================================
1 How To Use Attributes
2 ==============================================
3
4 .. contents::
5 :local:
6
7 Introduction
8 ============
9
10 Attributes in LLVM have changed in some fundamental ways. It was necessary to do
11 this to support expanding the attributes to encompass more than a handful of
12 attributes --- e.g. command line options. The old way of handling attributes
13 consisted of representing them as a bit mask of values. This bit mask was stored
14 in a "list" structure that was reference counted. The advantage of this was that
15 attributes could be manipulated with 'or's and 'and's. The disadvantage of this
16 was that there was limited room for expansion, and virtually no support for
17 attribute-value pairs other than alignment.
18
19 In the new scheme, an Attribute object represents a single attribute that's
20 uniqued. You use the "Attribute::get" methods to create a new Attribute
21 object. An attribute can be a single "enum" value (the enum being the
22 Attribute::AttrKind enum), a string representing a target-dependent attribute,
23 or an attribute-value pair. Some examples:
24
25 * Target-independent:   noinline, zext
26 * Target-dependent:     "no-sse", "thumb2"
27 * Attribute-value pair: "cpu" = "cortex-a8", align = 4
28
29 Note: for an attribute value pair, we expect a target-dependent attribute to
30 have a string for the value.
31
32 Attribute
33 =========
34 An Attribute object is designed to be passed around by value.
35
36 Because attributes are no longer represented as a bit mask, you will need to
37 convert any code which does treat them as a bit mask to use the new query
38 methods on the Attribute class.
39
40 AttributeSet
41 ============
42
43 The next class is the AttributeSet class. This replaces the old AttributeList
44 class. The AttributeSet stores a collection of Attribute objects for each kind
45 of object that may have an attribute associated with it: the function as a
46 whole, the return type, or the function's parameters. A function's attributes
47 are at index "AttributeSet::FunctionIndex"; the return type's attributes are at
48 index "AttributeSet::ReturnIndex"; and the function's parameters' attributes are
49 at indices 1, ..., n (where 'n' is the number of parameters). Most methods on
50 the AttributeSet class take an index parameter.
51
52 An AttributeSet is also a uniqued and immutable object. You create an
53 AttributeSet through the "AttributeSet::get" methods. You can add and remove
54 attributes, which result in the creation of a new AttributeSet.
55
56 An AttributeSet object is designed to be passed around by value.
57
58 Note: It is advised that you do *not* use the AttributeSet "Introspection"
59 methods (e.g. 'Raw', 'getRawPointer', etc.). These methods break encapsulation,
60 and may be removed in a future release (i.e. 4.0).
61
62 AttrBuilder
63 ================
64
65 Lastly, we have a 'builder' class to help create the AttributeSet object without
66 having to create several different intermediate uniqued AttributeSet
67 objects. The AttrBuilder class allows you to add and remove attributes at
68 will. The attributes won't be uniqued until you call the appropriate
69 "AttributeSet::get" method.
70
71 An AttrBuilder object is *not* designed to be passed around by value. It should
72 be passed by reference.
73
74 Note: It is advised that you do *not* use the "AttrBuilder::addRawValue()"
75 method or the "AttrBuilder(uint64_t Val)" c'tor. These are for backwards
76 compatibility and may be removed in a future release (i.e. 4.0).
77
78 And that's basically it! A lot of functionality is hidden behind these classes,
79 but the interfaces are pretty straight forward.
246246 GarbageCollection
247247 WritingAnLLVMPass
248248 TableGen/LangRef
249 HowToUseAttributes
249250
250251 :doc:`WritingAnLLVMPass`
251252 Information on how to write LLVM transformations and analyses.
311312 :doc:`MarkedUpDisassembly`
312313 This document describes the optional rich disassembly output syntax.
313314
315 :doc:`HowToUseAttributes`
316 Answers some questions about the new Attributes infrastructure.
314317
315318 Development Process Documentation
316319 =================================