1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.6"/>
<title>ViennaCL - The Vienna Computing Library: Memory Model</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">ViennaCL - The Vienna Computing Library
 <span id="projectnumber">1.7.1</span>
</div>
<div id="projectbrief">Free open-source GPU-accelerated linear algebra and solver library.</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.6 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('manual-memory.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark"> </span>Friends</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark"> </span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(11)"><span class="SelectionMark"> </span>Pages</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Memory Model </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>With the support of multiple compute backends, memory buffers need to be managed differently depending on whether CUDA, OpenCL or a plain host-based buffer is in use. These different <em>memory domains</em> are abstracted in a class <code><a class="el" href="classviennacl_1_1backend_1_1mem__handle.html" title="Main abstraction class for multiple memory domains. Represents a buffer in either main RAM...">viennacl::backend::mem_handle</a></code>, which is able to refer to a buffer in all three backends, possibly at the same time. Objects of type <code>mem_handle</code> are the building blocks of scalars, vectors and matrices in ViennaCL, see <a class="el" href="manual-types.html">Basic Types</a>.</p>
<p>The raw handles for each memory domain can be obtained via the member functions <code>cuda_handle()</code>, <code>opencl_handle()</code>, and <code><a class="el" href="namespaceviennacl_1_1traits.html#ab04b9165b9e95cbf5128840c9f4e42d5" title="Generic helper routine for extracting the RAM handle of a ViennaCL object. Non-const version...">ram_handle()</a></code>. Note that the former two may not be available if no support for the respective backend is activated using the preprocessor constants <code>VIENNACL_WITH_CUDA</code> and <code>VIENNACL_WITH_OPENCL</code>, see <a class="el" href="manual-installation.html#manual-installation-backends">Enabling OpenMP, OpenCL, or CUDA Backends</a></p>
<h1><a class="anchor" id="manual-memory-handle"></a>
Memory Handle Operations</h1>
<p>Each supported backend is required to support the following functions (arguments omitted for brevity, see reference documentation in <code>doc/doxygen</code> for details):</p>
<ul>
<li><code><a class="el" href="namespaceviennacl_1_1backend_1_1cpu__ram.html#a55bf912f3d21fcf7d348d59e1c8bef7d" title="Creates an array of the specified size in main RAM. If the second argument is provided, the buffer is initialized with data from that pointer. ">memory_create()</a></code>: Create a memory buffer</li>
<li><code><a class="el" href="namespaceviennacl_1_1backend_1_1cpu__ram.html#a307263f9deed5ce983ae50ebda5c1e0b" title="Copies 'bytes_to_copy' bytes from address 'src_buffer + src_offset' to memory starting at address 'ds...">memory_copy()</a></code>: Copy the (partial) contents of one buffer to another</li>
<li><code><a class="el" href="namespaceviennacl_1_1backend_1_1cpu__ram.html#a812c9e949c4a31f8ad34fe03af0f95aa" title="Writes data from main RAM identified by 'ptr' to the buffer identified by 'dst_buffer'. ">memory_write()</a></code>: Write from a memory location in CPU RAM to the buffer</li>
<li><code><a class="el" href="namespaceviennacl_1_1backend_1_1cpu__ram.html#abfa2dfe9a2ca51ad12d1204e558ece21" title="Reads data from a buffer back to main RAM. ">memory_read()</a></code>: Read from the buffer to a memory location in CPU RAM</li>
</ul>
<p>A common interface layer in <code><a class="el" href="namespaceviennacl_1_1backend.html" title="Namespace providing routines for handling the different memory domains. ">viennacl::backend</a></code> dispatches into the respective routines in the backend for the currently active memory domain of the handle.</p>
<h1><a class="anchor" id="manual-memory-switching"></a>
Querying and Switching Active Memory Domains</h1>
<p>The global default memory domain can be queried by </p>
<pre class="fragment">viennacl::backend::default_memory_type();
</pre><p>If the global memory domain should be changed to a new default, pass the new memory domain as parameter to <code><a class="el" href="namespaceviennacl_1_1backend.html#a0238c5401fc7e05c3641b1ad5e872458" title="Returns the default memory type for the given configuration. ">default_memory_type()</a></code>. For example, to allocate buffers in main memory even though OpenCL or CUDA are enabled, call </p>
<pre class="fragment">viennacl::backend::default_memory_type(viennacl::MAIN_MEMORY);
</pre><p>and all subsequent buffers are allocated in main memory unless specified otherwise.</p>
<p>A global change of the default memory domain is not thread-safe, hence one can specify the memory domain individually for each object holding one or more memory handles internally. Unless specified otherwise, such a <code>mem_handle</code> object creates its buffer for the default memory type. The current memory domain of a <code>mem_handle</code> can be queried using the member function <code>memory_domain()</code> and returns one of the values <code>MEMORY_NOT_INITIALIZED</code>, <code>MAIN_MEMORY</code>, <code>OPENCL_MEMORY</code>, or <code>CUDA_MEMORY</code> defined in the struct <code><a class="el" href="namespaceviennacl.html#a00b40450b6b2fd87aad3527d9b2084b8">viennacl::memory_types</a></code>.</p>
<p>The currently active memory handle can be switched from outside using the member function <code>switch_memory_domain()</code>. For example, to indicate that the memory referenced by a handle <code>h</code>, the line </p>
<pre class="fragment">h.switch_active_handle_id(viennacl::MAIN_MEMORY);
</pre><p>is sufficient. However, no memory is created, copied, or manipulated when switching the currently active handle, because a <code>mem_handle</code> object does not know what the buffer content is referring to and is thus not able to convert data between different memory domains if required.</p>
<p>In order to copy the contents of a memory buffer in one memory domain to a memory buffer in another memory domain within the same <code>mem_handle</code>-object, the data type must be supplied. This is accomplished using the function <code>viennacl::backend::switch_memory_domain(mem_handle, viennacl::memory_types)</code>, which takes the data type as template argument. Thus, in order to make current data of type <code>float</code> availabe in CPU RAM for a handle <code>h</code>, the function </p>
<pre class="fragment">viennacl::backend::switch_memory_domain<float>(h, viennacl::MAIN_MEMORY);
</pre><p>is sufficient.</p>
<p>If data should be transferred from one memory handle <code>h1</code> to another memory handle <code>h2</code>, the function <code>viennacl::backend::typesafe_memory_copy(h1, h2)</code> is provided. It takes the data type as template argument and ensures a data conversion between different memory domains if required (e.g. <code>cl_uint</code> to <code>unsigned int</code>). </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Wed Jan 20 2016 22:32:44 for ViennaCL - The Vienna Computing Library by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.6 </li>
</ul>
</div>
</body>
</html>
|
