blob: dc6bcb3941230a4afd181a311017260b319a1d16 [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
<!-- saved from url=(0013)about:internet -->
<?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" xmlns:xlink="http://www.w3.org/1999/xlink" pref:renderer="mathplayer-dl">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<style xmlns="" type="text/css">
/* This style sets a margin around the entire page */
html, body {
margin: 10px;
}
p {
font: normal 16px verdana, sans-serif;
margin: 0;
padding-bottom:12px;
}
h1 {
font: bold 25px verdana, sans-serif;
margin-top: 0;
margin-bottom: 3px;
padding-top: 0;
padding-bottom: 0;
}
h2 {
font: bold 19px verdana, sans-serif;
margin-top: 28px;
margin-bottom: 3px;
padding-top: 0;
padding-bottom: 0;
}
h3 {
font: bold 19px verdana, sans-serif !important;
margin-top: 28px;
margin-bottom: 3px;
padding-top: 0;
padding-bottom: 0;
}
li {
font: normal 16px verdana, sans-serif;
margin-top: 0;
margin-bottom: 18px;
padding-top: 0;
padding-bottom: 0;
}
.pdparam {
font: italic 16px verdana, sans-serif;
}
.term {
font: italic 16px verdana, sans-serif;
font-weight: normal;
}
.type {
font: normal 16px verdana, sans-serif !important;
}
.parameter {
font-style: italic;
}
a:link, a:visited {
color: blue;
text-decoration: none;
font: normal 16px;
}
a:hover {
background-color: #FFFF99;
font: normal 16px;
}
div.funcsynopsis {
text-align: left;
background-color: #e6e6e6;
font: normal 16px verdana, sans-serif;
padding-top: 10px;
padding-bottom: 10px;
}
div.funcsynopsis table {
border-collapse: separate;
font: normal 16px verdana, sans-serif;
}
div.funcsynopsis td {
background-color: #e6e6e6;
border: 0 solid #000;
padding: 1px;
font: normal 16px verdana, sans-serif;
}
div.refsect1 {
font-family: verdana, sans-serif;
font-size: 16px;
}
code.constant {
font: normal 16px courier new, monospace !important;
}
span.errorname {
font: normal 16px verdana, sans-serif !important;
}
code.function {
font: bold 16px verdana, sans-serif !important;
}
b.fsfunc {
font: bold 16px verdana, sans-serif !important;
}
code.varname {
font: italic 16px verdana, sans-serif;
}
code.replaceable {
font: italic 16px courier new, monospace;
}
code.funcdef {
font: normal 16px verdana, sans-serif !important;
}
.citerefentry {
font: normal 16px verdana, sans-serif !important;
}
.parameter {
font-style: italic;
}
code.fsfunc {
font: normal 16px verdana, sans-serif !important;
}
/* PARAMETER: This style controls spacing between the terms in Parameter section */
dt {
margin-top: 15px;
}
/* TABLES: These styles apply to all tables OTHER than the Synopsis and Example tables */
div.refsect1 table {
width: 100%;
margin-top: 10px;
background-color: #FFF;
border-collapse: collapse;
border-color: #000;
border-width: 1px;
font: normal 16px verdana, sans-serif;
}
div.refsect1 th {
border-collapse: collapse;
border-color: #000;
border-width: 1px;
font: bold 16px verdana, sans-serif;
}
div.refsect1 td {
background-color: #FFF;
padding: 5px;
vertical-align: text-top;
border-collapse: collapse;
border-color: #000;
border-width: 1px;
font: normal 16px verdana, sans-serif;
}
div.refsect1 p{
font: normal 16px verdana, sans-serif;
margin-top: 8px;
margin-bottom: 8px;
padding-top: 0;
padding-bottom: 0;
}
/* EXAMPLE: These styles apply only to the Example section */
div.refsect2 {
font: normal 16px courier new, monospace !important;
}
div.refsect2 table {
margin-top: 0;
background-color: #e6e6e6;
width: 100%;
border: 0 solid #000;
padding: 2px;
font: normal 16px courier new, monospace !important;
}
div.refsect2 td {
background-color: #e6e6e6;
font: normal 16px courier new, monospace !important;
white-space:pre;
}
/* COPYRIGHT: This style formats the text of the copyright statement at the bottom of the page */
div.refsect3 {
font: normal 11px verdana, sans-serif;
margin-top: 50px;
margin-bottom: 20px;
padding-top: 0;
padding-bottom: 0;
}
</style>
<title>Attributes of Variables</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1" />
<meta name="keywords" content=" &#10; Attributes of Variables&#10; " />
</head>
<body>
<div class="refentry">
<a id="idm1"></a>
<div class="titlepage"></div>
<div xmlns="" class="refnamediv">
<a xmlns="http://www.w3.org/1999/xhtml" id="Attributes of Variables"></a>
<h1>Attributes of Variables</h1>
<p>
Attributes of Variables.
</p>
</div>
<div class="refsect2">
<a id="synopsis"></a>
<h3>
</h3>
<div class="informaltable">
<table class="informaltable" border="0">
<colgroup>
<col align="left" class="col1" />
</colgroup>
<tbody>
<tr>
<td align="left">
__attribute__ ((aligned))
__attribute__ ((aligned (<span class="emphasis"><em>n</em></span>)))
__attribute__ ((packed))
__attribute__ ((endian(host)))
__attribute__ ((endian(device)))
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="refsect1">
<a id="description"></a>
<h2>Description</h2>
<p>
The keyword <code class="constant">__attribute__</code> allows
you to specify special attributes of variables or structure
fields. This keyword is followed by an attribute
specification inside double parentheses. The
<code class="code">aligned</code>, <code class="code">packed</code>, and <code class="code">endian</code> attribute qualifiers are defined below.
</p>
</div>
<div class="refsect2">
<a id="aligned"></a>
<h3>aligned (<code class="varname">alignment</code>)</h3>
<p>
The <code class="code">aligned (<span class="emphasis"><em>alignment</em></span>)</code> attribute specifies a minimum alignment for the variable or structure field, measured in bytes. For example, the declaration:
</p>
<p>
</p>
<div class="informaltable">
<table class="informaltable" border="0">
<colgroup>
<col align="left" class="col1" />
</colgroup>
<tbody>
<tr>
<td align="left"> <code class="code">int x __attribute__ ((aligned (16))) = 0;</code></td>
</tr>
</tbody>
</table>
</div>
<p>
</p>
<p>
causes the compiler to allocate the global variable <code class="code">x</code> on a 16-byte boundary. The alignment value specified must be a power of two.
</p>
<p>
You can also specify the alignment of structure fields. For example, to create double-word aligned <code class="code">int</code> pair, you could write:
</p>
<p>
</p>
<div class="informaltable">
<table class="informaltable" border="0">
<colgroup>
<col align="left" class="col1" />
</colgroup>
<tbody>
<tr>
<td align="left"> <code class="code">struct foo { int x[2] __attribute__ ((aligned (8))); };</code></td>
</tr>
</tbody>
</table>
</div>
<p>
</p>
<p>
This is an alternative to creating a union with a <code class="code">double</code> member that forces the union to be double-word aligned.
</p>
<p>
As in the preceding examples, you can explicitly specify the alignment (in bytes) that you
wish the compiler to use for a given variable or structure field. Alternatively, you can
leave out the alignment factor and just ask the compiler to align a variable or field to the
maximum useful alignment for the target machine you are compiling for. For example,
you could write:
</p>
<p>
</p>
<div class="informaltable">
<table class="informaltable" border="0">
<colgroup>
<col align="left" class="col1" />
</colgroup>
<tbody>
<tr>
<td align="left"> <code class="code">short array[3] __attribute__ ((aligned));</code></td>
</tr>
</tbody>
</table>
</div>
<p>
</p>
<p>
Whenever you leave out the alignment factor in an
<code class="code">aligned</code> attribute specification, the
OpenCL compiler automatically sets the alignment for the declared variable or field to
the largest alignment which is ever used for any data type on the target device you are
compiling for.
</p>
<p>
When used on a <code class="code">struct</code>, or <code class="code">struct</code> member,
the aligned <code class="code">attribute</code> can only increase
the alignment; in order to decrease it, the <code class="code">packed</code>
attribute must be specified as well.
When used as part of a <code class="code">typedef</code>,
the <code class="code">aligned</code> attribute can both increase and decrease
alignment, and specifying the <code class="code">packed</code>
attribute will generate a warning.
</p>
<p>
Note that the effectiveness of aligned attributes may be limited by inherent limitations of
the OpenCL device and compiler. For some devices, the OpenCL compiler may only be
able to arrange for variables to be aligned up to a certain maximum alignment. If the
OpenCL compiler is only able to align variables up to a maximum of 8 byte alignment,
then specifying <code class="code">aligned(16)</code> in an
<code class="code">__attribute__</code> will still only provide you with
8 byte alignment. See your platform-specific documentation for further information.
</p>
</div>
<div class="refsect2">
<a id="packed"></a>
<h3>packed</h3>
<p>
The <code class="code">packed</code> attribute specifies that
a variable or structure field should have the smallest
possible alignment -- one byte for a variable, unless you specify a larger value with the
<code class="code">aligned</code> attribute.
</p>
<p>
Here is a structure in which the field <code class="code">x</code> is packed,
so that it immediately follows <code class="code">a</code>:
</p>
<p>
</p>
<div class="informaltable">
<table class="informaltable" border="0">
<colgroup>
<col align="left" class="col1" />
</colgroup>
<tbody>
<tr>
<td align="left"> <code class="code">struct foo
{
char a;
int x[2] __attribute__ ((packed));
};</code></td>
</tr>
</tbody>
</table>
</div>
<p>
</p>
<p>
An attribute list placed at the beginning of a user-defined type applies to the variable of
that type and not the type, while attributes following the type body apply to the type.
</p>
<p>
For example:
</p>
<p>
</p>
<div class="informaltable">
<table class="informaltable" border="0">
<colgroup>
<col align="left" class="col1" />
</colgroup>
<tbody>
<tr>
<td align="left"> <code class="code">/* a has alignment of 128 */
__attribute__((aligned(128))) struct A {int i;} a;
/* b has alignment of 16 */
__attribute__((aligned(16))) struct B {double d;}
__attribute__((aligned(32))) b ;
struct A a1; /* a1 has alignment of 4 */
struct B b1; /* b1 has alignment of 32 */</code></td>
</tr>
</tbody>
</table>
</div>
<p>
</p>
</div>
<div class="refsect2">
<a id="endian"></a>
<h3>endian (<code class="varname">endiantype</code>)</h3>
<p>
The <code class="code">endian (<span class="emphasis"><em>endiantype</em></span>)</code> attribute determines the byte ordering of a variable.
<code class="code">endiantype</code> can be
set to <code class="code">host</code> indicating the variable uses the
endianness of the host processor or can be set
to <code class="code">device</code> indicating the variable uses the
endianness of the device on which the kernel
will be executed. The default is <code class="code">device</code>. For example:
</p>
<p>
</p>
<div class="informaltable">
<table class="informaltable" border="0">
<colgroup>
<col align="left" class="col1" />
</colgroup>
<tbody>
<tr>
<td align="left"> <code class="code">float4 *p __attribute__ ((endian(host)));</code></td>
</tr>
</tbody>
</table>
</div>
<p>
</p>
<p>
specifies that data stored in memory pointed to by <code class="code">p</code> will be in the host endian format.
</p>
</div>
<div class="refsect1">
<a id="specification"></a>
<h2>Specification</h2>
<p>
<img src="pdficon_small1.gif" />
<a href="http://www.khronos.org/registry/cl/specs/opencl-1.0.pdf#page=165" target="OpenCL Spec">OpenCL Specification</a>
</p>
</div>
<div class="refsect1">
<a id="seealso"></a>
<h2>Also see</h2>
<p>
<a class="citerefentry" href="attribute.html"><span class="citerefentry"><span class="refentrytitle">__attribute__</span></span></a>,
<a class="citerefentry" href="attributes-blocksAndControlFlow.html"><span class="citerefentry"><span class="refentrytitle">Blocks and Control-Flow Statement Attributes Attributes</span></span></a>,
<a class="citerefentry" href="attributes-types.html"><span class="citerefentry"><span class="refentrytitle">Types Attributes</span></span></a>
</p>
</div>
<div xmlns="" class="refsect3" lang="en" xml:lang="en"><a xmlns="http://www.w3.org/1999/xhtml" id="Copyright"></a><h4 xmlns="http://www.w3.org/1999/xhtml"></h4><img xmlns="http://www.w3.org/1999/xhtml" src="KhronosLogo.jpg" /><p xmlns="http://www.w3.org/1999/xhtml"></p>Copyright © 2007-2009 The Khronos Group Inc.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and/or associated documentation files (the
"Materials"), to deal in the Materials without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Materials, and to
permit persons to whom the Materials are furnished to do so, subject to
the condition that this copyright notice and permission notice shall be included
in all copies or substantial portions of the Materials.
</div>
</div>
</body>
</html>