RPCS3/llvm-mirror
1
0
Fork 0
mirror of https://github.com/RPCS3/llvm-mirror.git synced 2025-02-12 07:41:14 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Documentation: HowToUseAttributes: formatting (use monospaced font)

Browse Source 
llvm-svn: 174982
This commit is contained in:
Dmitri Gribenko 2013-02-12 18:26:08 +00:00
parent bb3116f965
commit e7a571489a
1 changed files with 56 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
docs/HowToUseAttributes.rst
View File

@ -1,6 +1,6 @@
============================================== =====================
How To Use Attributes How To Use Attributes
============================================== =====================
.. contents:: .. contents::
:local: :local:
@ -8,73 +8,74 @@ How To Use Attributes
Introduction Introduction
============ ============
Attributes in LLVM have changed in some fundamental ways. It was necessary to do Attributes in LLVM have changed in some fundamental ways. It was necessary to
this to support expanding the attributes to encompass more than a handful of 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 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 consisted of representing them as a bit mask of values. This bit mask was
in a "list" structure that was reference counted. The advantage of this was that stored in a "list" structure that was reference counted. The advantage of this
attributes could be manipulated with 'or's and 'and's. The disadvantage of this was that attributes could be manipulated with 'or's and 'and's. The
was that there was limited room for expansion, and virtually no support for disadvantage of this was that there was limited room for expansion, and
attribute-value pairs other than alignment. virtually no support for attribute-value pairs other than alignment.
In the new scheme, an Attribute object represents a single attribute that's 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 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 object. An attribute can be a single "enum" value (the enum being the
Attribute::AttrKind enum), a string representing a target-dependent attribute, ``Attribute::AttrKind`` enum), a string representing a target-dependent
or an attribute-value pair. Some examples: attribute, or an attribute-value pair. Some examples:
* Target-independent:   noinline, zext * Target-independent: ``noinline``, ``zext``
* Target-dependent:     "no-sse", "thumb2" * Target-dependent: ``"no-sse"``, ``"thumb2"``
* Attribute-value pair: "cpu" = "cortex-a8", align = 4 * Attribute-value pair: ``"cpu" = "cortex-a8"``, ``align = 4``
Note: for an attribute value pair, we expect a target-dependent attribute to Note: for an attribute value pair, we expect a target-dependent attribute to
have a string for the value. have a string for the value.
Attribute ``Attribute``
========= =============
An Attribute object is designed to be passed around by value. 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 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 convert any code which does treat them as a bit mask to use the new query
methods on the Attribute class. methods on the Attribute class.
AttributeSet ``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 The ``AttributeSet`` class replaces the old ``AttributeList`` class. The
having to create several different intermediate uniqued AttributeSet ``AttributeSet`` stores a collection of Attribute objects for each kind of
objects. The AttrBuilder class allows you to add and remove attributes at object that may have an attribute associated with it: the function as a
will. The attributes won't be uniqued until you call the appropriate whole, the return type, or the function's parameters. A function's attributes
"AttributeSet::get" method. 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 AttrBuilder object is *not* designed to be passed around by value. It should An ``AttributeSet`` is also a uniqued and immutable object. You create an
be passed by reference. ``AttributeSet`` through the ``AttributeSet::get`` methods. You can add and
remove attributes, which result in the creation of a new ``AttributeSet``.
Note: It is advised that you do *not* use the "AttrBuilder::addRawValue()" An ``AttributeSet`` object is designed to be passed around by value.
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). 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. LLVM 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)`` 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, And that's basically it! A lot of functionality is hidden behind these classes,
but the interfaces are pretty straight forward. but the interfaces are pretty straight forward.