| <?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>clSVMAlloc |
| <keywordset> |
| <keyword>clSVMAlloc</keyword> |
| </keywordset> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle> |
| clSVMAlloc |
| </refentrytitle> |
| |
| <refmiscinfo> |
| <copyright> |
| <year>2007-2013</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>3</manvolnum> |
| </refmeta> |
| |
| <!-- ================================ SYNOPSIS --> |
| |
| <refnamediv id="clSVMAlloc"> |
| <refname> |
| clSVMAlloc |
| </refname> |
| |
| <refpurpose> |
| Allocates a shared virtual memory (SVM) buffer that can be shared by the host and all devices in an OpenCL context that support shared virtual memory. |
| </refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv xmlns:xlink="http://www.w3.org/1999/xlink"><title></title> |
| <funcsynopsis> |
| <funcprototype> |
| <funcdef> |
| <link xlink:href="abstractDataTypes.html">void</link> <function> * clSVMAlloc</function> |
| </funcdef> |
| |
| <paramdef><link xlink:href="abstractDataTypes.html">cl_context</link><parameter>context</parameter></paramdef> |
| <paramdef><link xlink:href="enums.html#cl_svm_mem_flags">cl_svm_mem_flags</link><parameter>flags</parameter></paramdef> |
| <paramdef><link xlink:href="scalarDataTypes.html">size_t</link><parameter>size</parameter></paramdef> |
| <paramdef><link xlink:href="scalarDataTypes.html">cl_uint</link><parameter>alignment</parameter></paramdef> |
| |
| </funcprototype> |
| </funcsynopsis> |
| </refsynopsisdiv> |
| |
| <!-- ================================ PARAMETERS --> |
| |
| <refsect1 id="parameters"> |
| <title>Parameters</title> |
| <variablelist> |
| |
| <varlistentry> |
| <term><varname>context</varname></term> |
| <listitem> |
| <para>A valid OpenCL context used to create the SVM buffer.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> <varname>flags</varname> </term> |
| <listitem> |
| <para> |
| A bit-field that is used to specify |
| allocation and usage information. The following |
| table describes the possible values for <varname>flags</varname>. |
| </para> |
| |
| <!-- Table 5.13 --> |
| <informaltable frame="all"> |
| <tgroup cols="2" align="left" colsep="1" rowsep="1"> |
| <colspec colname="col1" colnum="1" /> |
| <colspec colname="col2" colnum="2" /> |
| <thead> |
| <row> |
| <entry>cl_svm_mem_flags</entry> |
| <entry>Description</entry> |
| </row> |
| </thead> |
| |
| <tbody> |
| <row> |
| <entry><constant>CL_MEM_READ_WRITE</constant></entry> |
| <entry> |
| This flag specifies that the SVM buffer will be read |
| and written by a kernel. This is the default. |
| </entry> |
| </row> |
| |
| <row> |
| <entry><constant>CL_MEM_WRITE_ONLY</constant></entry> |
| <entry> |
| <para> |
| This flag specifies that the SVM buffer will be written |
| but not read by a kernel. |
| </para> |
| <para> |
| Reading from a SVM buffer created with |
| <constant>CL_MEM_WRITE_ONLY</constant> inside a kernel is undefined. |
| </para> |
| <para> |
| <constant>CL_MEM_READ_WRITE</constant> and |
| <constant>CL_MEM_WRITE_ONLY</constant> are mutually exclusive. |
| </para> |
| </entry> |
| </row> |
| |
| <row> |
| <entry><constant>CL_MEM_READ_ONLY</constant></entry> |
| <entry> |
| <para> |
| This flag specifies that the SVM buffer object is a |
| read-only memory object when used inside a kernel. |
| </para> |
| <para> |
| Writing to a SVM buffer created with |
| <constant>CL_MEM_READ_ONLY</constant> inside a kernel is undefined. |
| </para> |
| <para> |
| <constant>CL_MEM_READ_WRITE</constant> or <constant>CL_MEM_WRITE_ONLY</constant> and |
| <constant>CL_MEM_READ_ONLY</constant> are mutually exclusive. |
| </para> |
| </entry> |
| </row> |
| |
| <row> |
| <entry><constant>CL_MEM_SVM_FINE_GRAIN_BUFFER</constant></entry> |
| <entry> |
| This specifies that the application wants the OpenCL |
| implementation to do a fine-grained allocation. |
| </entry> |
| </row> |
| |
| <row> |
| <entry><constant>CL_MEM_SVM_ATOMICS</constant></entry> |
| <entry> |
| This flag is valid only if |
| <constant>CL_MEM_SVM_FINE_GRAIN_BUFFER</constant> is specified in |
| <varname>flags</varname>. It is used to indicate that SVM atomic |
| operations can control visibility of memory accesses |
| in this SVM buffer. |
| </entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| |
| |
| |
| </listitem> |
| </varlistentry> |
| |
| <!-- END PARAMETER TABLE --> |
| |
| <varlistentry> |
| <term><varname>size</varname></term> |
| <listitem> |
| <para>The size in bytes of the SVM buffer to be allocated.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><varname>alignment</varname></term> |
| <listitem> |
| <para> |
| The minimum alignment in bytes that is required for |
| the newly created buffer’s |
| memory region. It must be a power of two up to the |
| largest data type supported by the OpenCL |
| device. For the full profile, the largest data type |
| is <type>long16</type>. For the embedded profile, it is |
| <type>long16</type> if the device supports 64-bit |
| integers; otherwise it is <type>int16</type>. If |
| alignment is 0, a |
| default alignment will be used that is equal to |
| the size of largest data type supported by the |
| OpenCL implementation. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| </refsect1> |
| |
| <!-- ================================ NOTES --> |
| <refsect1 id="notes"><title>Notes</title> |
| <para> |
| If <constant>CL_MEM_SVM_FINE_GRAIN_BUFFER</constant> is not |
| specified, the buffer can be created as a coarse |
| grained SVM allocation. Similarly, if <constant>CL_MEM_SVM_ATOMICS</constant> |
| is not specified, the buffer can be |
| created without support for SVM atomic |
| operations (refer to the OpenCL C++ kernel language and IL specifications). |
| </para> |
| |
| <para> |
| Calling <function>clSVMAlloc</function> does not itself |
| provide consistency for the shared memory region. When |
| the host can’t use the SVM atomic operations, it |
| must rely on OpenCL’s guaranteed memory |
| consistency at synchronization points. |
| </para> |
| |
| <para> |
| For SVM to be used efficiently, the host and any |
| devices sharing a buffer containing virtual |
| memory pointers should have the same endianness. |
| If the context passed to <function>clSVMAlloc</function> has |
| devices with mixed endianness and the OpenCL |
| implementation is unable to implement SVM |
| because of that mixed endianness, |
| <function>clSVMAlloc</function> will fail and return NULL. |
| </para> |
| |
| <para> |
| Although SVM is generally not supported for image objects, |
| <citerefentry><refentrytitle>clCreateImage</refentrytitle></citerefentry> |
| may create an image from a buffer (a 1D image from a buffer |
| or a 2D image from buffer) if the buffer specified |
| in its image description parameter is a SVM |
| buffer. Such images have a linear memory |
| representation so their memory can be |
| shared using SVM. However, fine grained sharing and |
| atomics are not supported for image reads and writes in a kernel. |
| </para> |
| |
| <para><!-- this is also inlcuded in the reference page for clCreateBuffer --> |
| If <citerefentry><refentrytitle>clCreateBuffer</refentrytitle></citerefentry> |
| is called with a pointer returned by |
| <function>clSVMAlloc</function> as its |
| <varname>host_ptr</varname> argument, and |
| <constant>CL_MEM_USE_HOST_PTR</constant> is set in its <varname>flags</varname> argument, |
| <citerefentry><refentrytitle>clCreateBuffer</refentrytitle></citerefentry> |
| will succeed and return a |
| valid non-zero buffer object as long as the <varname>size</varname> |
| argument to |
| <citerefentry><refentrytitle>clCreateBuffer</refentrytitle></citerefentry> |
| is no larger than the |
| <varname>size</varname> argument passed in the original |
| <function>clSVMAlloc</function> call. The new buffer object returned has the |
| shared memory as the underlying storage. Locations in |
| the buffer's underlying shared memory |
| can be operated on using atomic operations to the device's |
| level of support as defined in the |
| memory model. |
| </para> |
| </refsect1> |
| |
| <!-- ================================ ERRORS --> |
| |
| <refsect1 id="errors"><title>Errors</title> |
| <para> |
| Returns a valid non-NULL shared virtual memory address if the SVM buffer is |
| successfully allocated. Otherwise, like malloc, it returns a NULL pointer |
| value. <function>clSVMAlloc</function> will fail if: |
| </para> |
| |
| <itemizedlist mark="disc"> |
| <listitem> |
| <varname>context</varname> is not a valid context. |
| </listitem> |
| |
| <listitem> |
| <varname>flags</varname> does not contain |
| <constant>CL_MEM_SVM_FINE_GRAIN_BUFFER</constant> but does contain |
| <constant>CL_MEM_SVM_ATOMICS</constant>. |
| </listitem> |
| |
| <listitem> |
| Values specified in <varname>flags</varname> do not follow |
| rules described for supported values in the table above. |
| </listitem> |
| |
| <listitem> |
| <constant>CL_MEM_SVM_FINE_GRAIN_BUFFER</constant> or |
| <constant>CL_MEM_SVM_ATOMICS</constant> is specified in |
| <varname>flags</varname> and these are not supported |
| by at least one device in <varname>context</varname>. |
| </listitem> |
| |
| <listitem> |
| The values specified in <varname>flags</varname> are |
| not valid i.e. don’t match those defined in the table above. |
| </listitem> |
| |
| <listitem> |
| <varname>size</varname> is 0 or > <constant>CL_DEVICE_MAX_MEM_ALLOC_SIZE</constant> |
| value for any device in <varname>context</varname>. |
| </listitem> |
| |
| <listitem> |
| <varname>alignment</varname> is not a power of two |
| or the OpenCL implementation cannot support the |
| specified alignment for at least one device in <varname>context</varname>. |
| </listitem> |
| |
| <listitem> |
| There was a failure to allocate resources. |
| </listitem> |
| |
| </itemizedlist> |
| </refsect1> |
| |
| <!-- ================================ 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="clSVMAlloc">OpenCL Specification</olink> |
| </para> |
| </refsect1> |
| |
| <!-- ================================ ALSO SEE --> |
| |
| <refsect1 id="seealso"><title>Also see</title> |
| <para> |
| <citerefentry><refentrytitle>clSVMFree</refentrytitle></citerefentry>, |
| <citerefentry href="sharedVirtualMemory"><refentrytitle>Shared Virtual Memory Functions</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> |
| |
| <!-- 9-Nov-2015, API ver 2.1 rev 19; Ext ver 2.1 rev 10; C lang ver 2.0 rev 30 --> |
| </refentry> |
| |
