OpenFAM.github.io/fam_create_region.html at master · OpenFAM/OpenFAM.github.io · GitHub

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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
<!DOCTYPE html>
<html lang="en">
<head>
<link rel="stylesheet" type="text/css" href="styles/style.css">
<title>OpenFAM: A library for programming Fabric-Attached Memory</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
	<header>
		<h1>OpenFAM Reference Implementation</h1>
	</header>
	<section>
		<nav>
			<ul>
				<li><a href="index.html">Home</a></li>
				<li><a href="release_notes.html">Release Notes</a></li>
				<li><a href="limitations.html">Design Choices</a></li>
				<li><a href="errors.html">Exceptions and Error Codes</a></li>
				<li><a href="services.html">Services</a></li>
				<li><a href="config_files.html">Configuration Files</a></li>
			</ul>
			<hr>
			Initialization and Finalization
			<ul>
				<li><a href="fam_initialize.html">fam_initialize</a></li>
				<li><a href="fam_finalize.html">fam_finalize</a></li>
				<li><a href="fam_abort.html">fam_abort</a></li>
			</ul>
			<hr>
			Options &amp; Query
			<ul>
				<li><a href="fam_list_options.html">fam_list_options</a></li>
				<li><a href="fam_get_option.html">fam_get_option</a></li>
				<li><a href="fam_lookup.html">fam_lookup</a></li>
				<li><a href="fam_stat.html">fam_stat</a></li>
			</ul>
			<hr>
			Memory Allocation
			<ul>
				<li><a href="fam_create_region.html">fam_create_region</a></li>
				<li><a href="fam_destroy_region.html">fam_destroy_region</a></li>
				<li><a href="fam_resize_region.html">fam_resize_region</a></li>
				<li><a href="fam_allocate.html">fam_allocate</a></li>
				<li><a href="fam_deallocate.html">fam_deallocate</a></li>
				<li><a href="fam_change_permissions.html">fam_change_permissions</a></li>
				<li><a href="fam_close.html">fam_close</a></li>
			</ul>
			<hr>
			Memory Map
			<ul>
				<li><a href="fam_map.html">fam_map</a></li>
				<li><a href="fam_unmap.html">fam_unmap</a></li>
			</ul>
			<hr>
			Data Path Operations
			<ul>
				<li><a href="fam_get.html">fam_get</a></li>
				<li><a href="fam_put.html">fam_put</a></li>
				<li><a href="fam_gather.html">fam_gather</a></li>
				<li><a href="fam_scatter.html">fam_scatter</a></li>
				<li><a href="fam_copy.html">fam_copy</a></li>
				<li><a href="fam_copy_wait.html">fam_copy_wait</a></li>
                                <li><a href="fam_backup.html">fam_backup</a></li>
                                <li><a href="fam_backup_wait.html">fam_backup_wait</a></li>
                                <li><a href="fam_restore.html">fam_restore</a></li>
                                <li><a href="fam_restore_wait.html">fam_restore_wait</a></li>
                                <li><a href="fam_delete_backup.html">fam_delete_backup</a></li>
                                <li><a href="fam_delete_backup_wait.html">fam_delete_backup_wait</a></li>
			</ul>
			<hr>
			Atomics
			<ul>
				<li><a href="fam_set.html">fam_set</a></li>
				<li><a href="fam_add.html">fam_add</a></li>
				<li><a href="fam_subtract.html">fam_subtract</a></li>
				<li><a href="fam_min.html">fam_min</a></li>
				<li><a href="fam_max.html">fam_max</a></li>
				<li><a href="fam_and.html">fam_and</a></li>
				<li><a href="fam_or.html">fam_or</a></li>
				<li><a href="fam_xor.html">fam_xor</a></li>
				<li><a href="fam_fetch_TYPE.html">fam_fetch_TYPE</a></li>
				<li><a href="fam_swap.html">fam_swap</a></li>
				<li><a href="fam_compare_swap.html">fam_compare_swap</a></li>
				<li><a href="fam_fetch_add.html">fam_fetch_add</a></li>
				<li><a href="fam_fetch_subtract.html">fam_fetch_subtract</a></li>
				<li><a href="fam_fetch_min.html">fam_fetch_min</a></li>
				<li><a href="fam_fetch_and.html">fam_fetch_and</a></li>
				<li><a href="fam_fetch_max.html">fam_fetch_max</a></li>
				<li><a href="fam_fetch_or.html">fam_fetch_or</a></li>
				<li><a href="fam_fetch_xor.html">fam_fetch_xor</a></li>
			</ul>
			<hr>
			Ordering
			<ul>
				<li><a href="fam_barrier_all.html">fam_barrier_all</a></li>
				<li><a href="fam_fence.html">fam_fence</a></li>
				<li><a href="fam_quiet.html">fam_quiet</a></li>
                                <li><a href="fam_progress.html">fam_progress</a></li>
                                <li><a href="fam_context_open.html">fam_context_open</a></li>
                                <li><a href="fam_context_close.html">fam_context_close</a></li>
			</ul>
			<hr>
		</nav>
		<article>
		<h1 class="code">openfam::fam::fam_create_region</h1>
	<p>Create a new region in FAM.</p>
	<h2>Synopsis</h2>
	<p class="code">Fam_Region_Descriptor *fam_create_region(char *name, uint64_t
		size, mode_t permissions, Fam_Region_Attributes* regionAttributes);</p>
	<h2>Description</h2>
	<p>This method creates a region in FAM for subsequent use</p>
	<h2>Input Arguments</h2>
	<table>
		<tbody>
			<tr>
				<th>
					Name
				</th>
				<th>
					Description
				</th>
			</tr>
			<tr>
				<td class="code">
					name
				</td>
				<td>
					Name of the region to be created.
				</td>
			</tr>
			<tr>
				<td class="code">
					size
				</td>
				<td>
					Requested size of the region in bytes.
				</td>
			</tr>
			<tr>
				<td class="code">
					permissions
				</td>
				<td>
					Permissions to be associated with this region.
				</td>
			</tr>
			<tr>
				<td class="code">
					regionAttributes
				</td>
				<td>
					Is a structure that holds region attributes such as:

				<p>
					<b>redundancyLevel</b> represents the redundancy level for the data items within the region. The supported values for redundancyLevel are: {DEFAULT, NONE, RAID1, RAID5} . The current DEFAULT is NONE.
				</p>
				<p>
					<b>memoryType</b> denotes the type of memory the region is created on. The supported values for memoryType are: {DEFAULT, VOLATILE, PERSISTENT}. PERSISTENT regions will be created in persistent memory, while VOLATILE regions will be created in DRAM. The current DEFAULT is VOLATILE.
				</p>
				<p>
					<b>interleaveEnable</b> denotes if data item interleaving is enabled for the region. The supported values are: {DEFAULT, ENABLE, DISABLE}. A value of DISABLE implies that data items within the region are not interleaved across memory servers, and each data item is hosted within a single memory server (subject to redundancyLevel). A value of ENABLE indicates data item interleaving is enabled, and data items are striped across memory servers using a system-defined interleave block size. The current DEFAULT value is ENABLE.
				</p>
 <p>
      <b>permissionLevel</b> attribute signifies the permission level of the data items allocated in the region. The supported values are: {DEFAULT, REGION, DATAITEM}. A value of REGION implies that the data items allocated within the region inherit the permission from the region. A value of DATAITEM indicates that the data items allocated within the region can have differ    ent permission than that of the region. permissionLevel attribute is also tied with the underlying memory registration strategy. If permissionLevel is REGION, the entire region memory is registered for RMA operation during region creation. But, if the value is DATAITEM, individual data item memory is registered at the time of allocation of that data item. The current DEFAULT value is REGION. </p>
				</td>
			</tr>
		</tbody>
	</table>
	<p>&nbsp;</p>
	<h2>Return Values</h2>
	<p>Descriptor to the created region. Throws <code>Fam_Exception</code> on error.</p>
	<h2>Fam error numbers</h2>
	<table>
	<tbody>
	<tr><th>Error</th><th>Description</th></tr>
	<tr><td class="code">FAM_ERR_NOPERM</td><td>Caller does not have access rights.</td></tr>
	<tr><td class="code">FAM_ERR_ALREADYEXIST</td><td>Region name is already present in FAM.</td></tr>
	<tr><td class="code">FAM_ERR_NAME_TOO_LONG</td><td>Region name too long.</td></tr>
	<tr><td class="code">FAM_ERR_NOT_CREATED</td><td>Region creation in FAM failed.</td></tr>
	<tr><td class="code">FAM_ERR_RPC</td><td>Communication error from grpc layer.</td></tr>
	<tr><td class="code">FAM_ERR_RPC_CLIENT_NOTFOUND</td><td>RPC service not available.</td></tr>
	<tr><td class="code">FAM_ERR_METADATA</td><td>Metadata service error.</td></tr>
	<tr><td class="code">FAM_ERR_MEMORY</td><td>Memory service error.</td></tr>
	<tr><td class="code">FAM_ERR_RESOURCE</td><td>Resource not available.</td></tr>
	</tbody></table>
	<h2>Notes</h2>
	<p>Note that the system may round up the actual size of the region
		to align memory boundaries. Currently the maximum size of a region is
		limited to 16 EiB by the API. See <a href="limitations.html">Design Choices</a>
		for the current design limits within the OpenFAM reference implementation.
		Also note that at present maximum region name length supported is 40 characters.
		</p>
	<p><code>Fam_Region_Descriptor</code> provides a method to retrieve an opaque read-only data structure called
	<code>Fam_Global_Descriptor</code> which represents the region in FAM. <code>Fam_Global_Descriptor</code>
	can be freely copied, and shared across processing nodes by the program, and is portable
	across operating system and program instances.</p>
<pre>
// Fam_Global_Descriptor Fam_Region_Descriptor::get_global_descriptor();
Fam_Global_Descriptor gDescriptor = regionDescriptor-&gt;get_global_descriptor();
</pre>
	<p><code>Fam_Region_Descriptor</code> can be instantiated from <code>Fam_Global_Descriptor</code> using the following constructor.</p>
<pre>
// Fam_Region_Descriptor::Fam_Region_Descriptor(Fam_Global_Descriptor gDescriptor);
Fam_Region_Descriptor *rd = new Fam_Region_Descriptor(gDescriptor);
</pre>
	<h2 id="e1">Example</h2>
<pre>
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;
#include &lt;fam/fam.h&gt;
#include &lt;fam/fam_exception.h&gt;
using namespace std;
using namespace openfam;

int main(void) {

	fam *myFam = new fam();

	// .. initialization code here

	    Fam_Region_Attributes* regionAttributes = (Fam_Region_Attributes*)calloc(1, sizeof(Fam_Region_Attributes));
	try {
	    	regionAttributes-&gt;memoryType = VOLATILE;
		// create a 10 GB region with 0777 permissions for given region attributes
		Fam_Region_Descriptor *rd = myFam-&gt;fam_create_region("myRegion", (uint64_t)10000000000, 0777, regionAttributes);

		/ use the created region...
		printf("fam_create_region successful\n");

		// ... continuation code here

		// we are finished. Destroy the region and everything in it
		myFam-&gt;fam_destroy_region(rd);
		printf("fam_destroy_region successful\n");
	} catch (Fam_Exception &amp;e) {
		printf("Create/Destroy region failed: %d: %s\n", e.fam_error(), e.fam_error_msg());
	}
	free(regionAttributes);
	// ... finalization code here

}
</pre>
		</article>
	</section>
	<footer>
		<p>Copyright 2021-23, Hewlett Packard Enterprise Development Co, LLP</p>
	</footer>
</body>
</html>