From 0013a5d87b8b51bb6d563dbb7b96978bed9d3ac3 Mon Sep 17 00:00:00 2001 From: Joe Abbey Date: Tue, 12 Feb 2013 11:45:22 +0000 Subject: 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 --- docs/HowToUseAttributes.rst | 80 +++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 3 ++ 2 files changed, 83 insertions(+) create mode 100644 docs/HowToUseAttributes.rst (limited to 'docs') diff --git a/docs/HowToUseAttributes.rst b/docs/HowToUseAttributes.rst new file mode 100644 index 0000000000..48725c7399 --- /dev/null +++ b/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. diff --git a/docs/index.rst b/docs/index.rst index e5b08457d6..8f22ef2a77 100644 --- a/docs/index.rst +++ b/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 ================================= -- cgit v1.2.3