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
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
<!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: User-Provided OpenCL Contexts</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-custom-contexts.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">User-Provided OpenCL Contexts </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Many projects need similar basic linear algebra operations, but essentially operate in their own OpenCL context. To provide the functionality and convenience of ViennaCL to such existing projects, existing contexts can be passed to ViennaCL and memory objects can be wrapped into the basic linear algebra types <code>vector</code>, <code>matrix</code>, or <code>compressed_matrix</code>. This chapter is devoted to the description of the necessary steps to use ViennaCL on contexts provided by the library user.</p>
<dl class="section note"><dt>Note</dt><dd>An example of providing a custom context to ViennaCL can be found in <code>examples/tutorial/custom-contexts.cpp</code></dd></dl>
<h1><a class="anchor" id="manual-custom-contexts-passing"></a>
Passing Contexts to ViennaCL</h1>
<p>ViennaCL is able to handle an arbitrary number of contexts, which are identified by a key value of type <code>long</code>. By default, ViennaCL operates on the context identified by <code>0</code>, unless the user switches the context, cf. <a class="el" href="manual-multi-device.html">Configuring OpenCL Contexts and Devices</a>.</p>
<p>According to the OpenCL standard, a context contains devices and queues for each device. Thus, it is assumed in the following that the user has successfully created a context with one or more devices and one or more queues per device.</p>
<p>In the case that the context contains only one device <code>my_device</code> and one queue <code>my_queue</code>, the context can be passed to ViennaCL with the code </p>
<div class="fragment"><div class="line">cl_context my_context = ...; <span class="comment">//a context</span></div>
<div class="line">cl_device_id my_device = ...; <span class="comment">//a device in my_context</span></div>
<div class="line">cl_command_queue my_queue = ...; <span class="comment">//a queue for my_device</span></div>
<div class="line"></div>
<div class="line"><span class="comment">//supply existing context 'my_context'</span></div>
<div class="line"><span class="comment">// with one device and one queue to ViennaCL using id '0':</span></div>
<div class="line"><a class="code" href="namespaceviennacl_1_1ocl.html#add1725d48cfd159ce187e287369d1cdb">viennacl::ocl::setup_context</a>(0, my_context, my_device, my_queue);</div>
</div><!-- fragment --><p> If a context ID other than <code>0</code>, say, <code>id</code> is used, the user-defined context has to be selected using </p>
<div class="fragment"><div class="line"><a class="code" href="namespaceviennacl_1_1ocl.html#acc1a7460a9ff237b7c0306c32c3d34c6">viennacl::ocl::switch_context</a>(<span class="keywordtype">id</span>);</div>
</div><!-- fragment --><p>It is also possible to provide a context with several devices and multiple queues per device. To do so, the device IDs have to be stored in a STL vector and the queues in a STL map: </p>
<div class="fragment"><div class="line">cl_context my_context = ...; <span class="comment">//a context</span></div>
<div class="line"></div>
<div class="line">cl_device_id my_device1 = ...; <span class="comment">//a device in my_context</span></div>
<div class="line">cl_device_id my_device2 = ...; <span class="comment">//another device in my_context</span></div>
<div class="line">...</div>
<div class="line"></div>
<div class="line">cl_command_queue my_queue1 = ...; <span class="comment">//a queue for my_device1</span></div>
<div class="line">cl_command_queue my_queue2 = ...; <span class="comment">//another queue for my_device1</span></div>
<div class="line">cl_command_queue my_queue3 = ...; <span class="comment">//a queue for my_device2</span></div>
<div class="line">...</div>
<div class="line"></div>
<div class="line"><span class="comment">// setup existing devices for ViennaCL:</span></div>
<div class="line">std::vector<cl_device_id> my_devices;</div>
<div class="line">my_devices.push_back(my_device1);</div>
<div class="line">my_devices.push_back(my_device2);</div>
<div class="line">...</div>
<div class="line"></div>
<div class="line"><span class="comment">// setup existing queues for ViennaCL:</span></div>
<div class="line">std::map<cl_device_id,</div>
<div class="line"> std::vector<cl_command_queue> > my_queues;</div>
<div class="line">my_queues[my_device1].push_back(my_queue1);</div>
<div class="line">my_queues[my_device1].push_back(my_queue2);</div>
<div class="line">my_queues[my_device2].push_back(my_queue3);</div>
<div class="line">...</div>
<div class="line"></div>
<div class="line"><span class="comment">// supply existing context with multiple devices</span></div>
<div class="line"><span class="comment">// and queues to ViennaCL using id '0':</span></div>
<div class="line">viennacl::ocl::setup_context(0, my_context, my_devices, my_queues);</div>
</div><!-- fragment --><p> It is not necessary to pass all devices and queues created within a particular context to ViennaCL, only those which ViennaCL should use have to be passed. ViennaCL will by default use the first queue on each device. The user has to care for appropriate synchronization between different queues.</p>
<dl class="section note"><dt>Note</dt><dd>ViennaCL does not destroy the provided context automatically upon exit. The user should thus call <code>clReleaseContext()</code> as usual for destroying the context.</dd></dl>
<h1><a class="anchor" id="manual-custom-contexts-wrapping"></a>
Wrapping Existing Memory with ViennaCL Types</h1>
<p>Now as the user provided context is supplied to ViennaCL, user-created memory objects have to be wrapped into ViennaCL data-types in order to use the full functionality. Typically, one of the types <code>scalar</code>, <code>vector</code>, <code>matrix</code> and <code>compressed_matrix</code> are used: </p>
<div class="fragment"><div class="line">cl_mem my_memory1 = ...;</div>
<div class="line">cl_mem my_memory2 = ...;</div>
<div class="line">cl_mem my_memory3 = ...;</div>
<div class="line">cl_mem my_memory4 = ...;</div>
<div class="line">cl_mem my_memory5 = ...;</div>
<div class="line"></div>
<div class="line"><span class="comment">// wrap my_memory1 into a vector of size 10</span></div>
<div class="line"><a class="code" href="classviennacl_1_1vector.html">viennacl::vector<float></a> my_vec(my_memory1, 10);</div>
<div class="line"></div>
<div class="line"><span class="comment">// wrap my_memory2 into a row-major matrix of size 10x10</span></div>
<div class="line"><a class="code" href="classviennacl_1_1matrix.html">viennacl::matrix<float></a> my_matrix(my_memory2, 10, 10);</div>
<div class="line"></div>
<div class="line"><span class="comment">// wrap my_memory3 into a CSR sparse matrix with 10 rows and 20 nonzeros</span></div>
<div class="line"><a class="code" href="classviennacl_1_1compressed__matrix.html">viennacl::compressed_matrix<float></a> my_sparse(my_memory3,</div>
<div class="line"> my_memory4,</div>
<div class="line"> my_memory5, 10, 10, 20);</div>
<div class="line"></div>
<div class="line"><span class="comment">// use my_vec, my_matrix, my_sparse as usual</span></div>
</div><!-- fragment --><p> The following has to be emphasized:</p>
<ul>
<li>Resize operations on ViennaCL data types typically results in the object owning a new piece of memory.</li>
<li><a class="el" href="namespaceviennacl.html#a10b7f8cf6b8864a7aa196d670481a453" title="Copies a circulant matrix from the std::vector to the OpenCL device (either GPU or multi-core CPU) ...">copy()</a> operations from CPU RAM usually allocate new memory, so wrapped memory is ``forgotten''</li>
<li>On construction of the ViennaCL object, <code>clRetainMem()</code> is called once for the provided memory handle. Similarly, <code>clReleaseMem()</code> is called as soon as the memory is not used any longer.</li>
</ul>
<dl class="section note"><dt>Note</dt><dd>The user has to ensure that the provided memory is larger or equal to the size of the wrapped object.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Be aware the wrapping the same memory object into several different ViennaCL objects can have unwanted side-effects. </dd>
<dd>
In particular, wrapping the same memory in two ViennaCL vectors implies that if the entries of one of the vectors is modified, this is also the case for the second. </dd></dl>
</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>
|
