sdk/1.0/docs/man/attributes-variables.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
              "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry>
    <refentryinfo>
        <keywordset>
            <keyword>                            
                Attributes of Variables
            </keyword>
        </keywordset>
    </refentryinfo>

    <refmeta>                                    
        <refentrytitle>Attributes of Variables</refentrytitle>

        <refmiscinfo>
            <copyright>
                <year>2007-2009</year>
                <holder>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.</holder>
            </copyright>
        </refmiscinfo>
        <manvolnum>2</manvolnum>
    </refmeta>

<!-- ================================ SYNOPSIS -->

    <refnamediv id="Attributes of Variables">             
        <refname>Attributes of Variables</refname>

        <refpurpose>
            Attributes of Variables.
        </refpurpose>
    </refnamediv>


    <!-- ALTERNATIVE SYNTAX SYNOPSIS (NON-FUNCTION) -->
    <refsect2 id="synopsis">
        <title>
        </title>

        <informaltable frame="none">
            <tgroup cols="1" align="left" colsep="0" rowsep="0">
                <colspec colname="col1" colnum="1" />
                <tbody>
                    <row>
                        <entry>
    __attribute__ ((aligned))
    __attribute__ ((aligned (<emphasis>n</emphasis>)))
    __attribute__ ((packed))
    __attribute__ ((endian(host)))
    __attribute__ ((endian(device))) 
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>
    </refsect2>


<!-- ================================ DESCRIPTION  -->

    <refsect1 id="description"><title>Description</title>
        <para>
The keyword <constant>__attribute__</constant> allows
you to specify special attributes of variables or structure
fields. This keyword is followed by an attribute
specification inside double parentheses. The
<code>aligned</code>, <code>packed</code>, and <code>endian</code> attribute qualifiers are defined below.
        </para>
</refsect1>

<refsect2 id="aligned"><title>aligned (<varname>alignment</varname>)</title> 
	<!-- Using refsect2 so we can have shaded backgrounds behind examples  -->

        <para>
The <code>aligned (<emphasis>alignment</emphasis>)</code> attribute specifies a minimum alignment for the variable or structure field, measured in bytes. For example, the declaration:
        </para>
<para>
        <informaltable frame="none">
            <tgroup cols="1" align="left" colsep="0" rowsep="0">
                <colspec colname="col1" colnum="1" />
                <tbody>
                    <row>
                        <entry>    <code>int x __attribute__ ((aligned (16))) = 0;</code></entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>		
</para>	
		
        <para>
causes the compiler to allocate the global variable <code>x</code> on a 16-byte boundary. The alignment value specified must be a power of two.
        </para>

        <para>
You can also specify the alignment of structure fields. For example, to create double-word aligned <code>int</code> pair, you could write:
        </para>
<para>
        <informaltable frame="none">
            <tgroup cols="1" align="left" colsep="0" rowsep="0">
                <colspec colname="col1" colnum="1" />
                <tbody>
                    <row>
                        <entry>    <code>struct foo { int x[2] __attribute__ ((aligned (8))); };</code></entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>		
</para>			
        <para>
This is an alternative to creating a union with a <code>double</code> member that forces the union to be double-word aligned.
        </para>

        <para>
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:
        </para>
<para>
        <informaltable frame="none">
            <tgroup cols="1" align="left" colsep="0" rowsep="0">
                <colspec colname="col1" colnum="1" />
                <tbody>
                    <row>
                        <entry>    <code>short array[3] __attribute__ ((aligned));</code></entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>		
</para>

        <para>
Whenever you leave out the alignment factor in an
<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.
        </para>

        <para>
When used on a <code>struct</code>, or <code>struct</code> member,
the aligned <code>attribute</code> can only increase
the alignment; in order to decrease it, the <code>packed</code>
attribute must be specified as well.
When used as part of a <code>typedef</code>,
the <code>aligned</code> attribute can both increase and decrease
alignment, and specifying the <code>packed</code>
attribute will generate a warning.
        </para>

        <para>
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>aligned(16)</code> in an
<code>__attribute__</code> will still only provide you with
        8 byte alignment. See your platform-specific documentation for further information.
        </para>
</refsect2>

<refsect2 id="packed"><title>packed</title> 
	<!-- Using refsect2 so we can have shaded backgrounds behind examples  -->
        <para>
The <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>aligned</code> attribute.
        </para>

        <para>
Here is a structure in which the field <code>x</code> is packed,
so that it immediately follows <code>a</code>:
        </para>
		
		
<para>
        <informaltable frame="none">
            <tgroup cols="1" align="left" colsep="0" rowsep="0">
                <colspec colname="col1" colnum="1" />
                <tbody>
                    <row>
                        <entry>    <code>struct foo
    {
        char a;
        int x[2] __attribute__ ((packed));
    };</code></entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>		
</para>
        <para>
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.
        </para>

        <para>
For example:
        </para>
<para>
        <informaltable frame="none">
            <tgroup cols="1" align="left" colsep="0" rowsep="0">
                <colspec colname="col1" colnum="1" />
                <tbody>
                    <row>
                        <entry>    <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></entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>		
</para>		
</refsect2>		


<refsect2 id="endian"><title>endian (<varname>endiantype</varname>)</title> 
	<!-- Using refsect2 so we can have shaded backgrounds behind examples  -->

        <para>
The <code>endian (<emphasis>endiantype</emphasis>)</code> attribute determines the byte ordering of a variable.
<code>endiantype</code> can be
set to <code>host</code> indicating the variable uses the
endianness of the host processor or can be set
to <code>device</code> indicating the variable uses the
endianness of the device on which the kernel
will be executed. The default is <code>device</code>. For example:
        </para>

<para>
        <informaltable frame="none">
            <tgroup cols="1" align="left" colsep="0" rowsep="0">
                <colspec colname="col1" colnum="1" />
                <tbody>
                    <row>
                        <entry>    <code>float4 *p   __attribute__ ((endian(host)));</code></entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>		
</para>		
        <para>
specifies that data stored in memory pointed to by <code>p</code> will be in the host endian format.
        </para>

    </refsect2>


<!-- ================================ EXAMPLE  -->
<!-- DO NOT DELETE IN CASE AN EXAMPLE IS ADDED IN THE FUTURE -->
<!--
    <refsect2 id="example1">
        <title>
            Example
        </title>

        <informaltable frame="none">
            <tgroup cols="1" align="left" colsep="0" rowsep="0">
                <colspec colname="col1" colnum="1" />
                <tbody>
                    <row>
                        <entry>
                            Example goes here - it will be set in "code" type with white space preserved.
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>
    </refsect2>
-->


<!-- ================================ SPECIFICATION  -->
<!-- Set the "uri" attribute in the <olink /> element to the "named destination" for the PDF page
-->
    <refsect1 id="specification"><title>Specification</title>
        <para>
            <imageobject>
                <imagedata fileref="pdficon_small1.gif" format="gif" />
            </imageobject>
                                                 
            <olink uri="attributes-variables">OpenCL Specification</olink>
        </para>
    </refsect1>


<!-- ================================ ALSO SEE  -->

    <refsect1 id="seealso"><title>Also see</title>

        <para>
<citerefentry href="attribute"><refentrytitle>__attribute__</refentrytitle></citerefentry>, 
<citerefentry href="attributes-blocksAndControlFlow"><refentrytitle>Blocks and Control-Flow Statement Attributes Attributes</refentrytitle></citerefentry>, 
<citerefentry href="attributes-types"><refentrytitle>Types Attributes</refentrytitle></citerefentry>
        </para>				
    </refsect1>



<!-- ============================== COPYRIGHT -->
<!-- Content included from copyright.inc.xsl -->

    <refsect3 id="Copyright"><title></title>
		<imageobject>
                <imagedata fileref="KhronosLogo.jpg" format="jpg" />
        </imageobject>
		<para />
    </refsect3>

</refentry>