Skip to content

Commit 2bff6a8

Browse files
bratpiorkabratpiorka
committed
flatten and cleanup provider ops structure ops
1 parent 861e8f4 commit 2bff6a8

22 files changed

+369
-374
lines changed

‎include/umf/memory_provider.h

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
/*
22
*
3-
* Copyright (C) 2023-2024 Intel Corporation
3+
* Copyright (C) 2023-2025 Intel Corporation
44
*
55
* Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
66
* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
@@ -179,7 +179,7 @@ umfMemoryProviderGetIPCHandle(umf_memory_provider_handle_t hProvider,
179179
void *providerIpcData);
180180

181181
///
182-
/// @brief Release IPC handle retrieved with get_ipc_handle function.
182+
/// @brief Release IPC handle retrieved with ipc_get_handle function.
183183
/// @param hProvider [in] handle to the memory provider.
184184
/// @param providerIpcData [in] pointer to the IPC opaque data structure.
185185
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.

‎include/umf/memory_provider_ops.h

Lines changed: 124 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -19,140 +19,24 @@ extern "C" {
1919
/// @brief Version of the Memory Provider ops structure.
2020
/// NOTE: This is equal to the latest UMF version, in which the ops structure
2121
/// has been modified.
22-
#define UMF_PROVIDER_OPS_VERSION_CURRENT UMF_MAKE_VERSION(0, 11)
23-
24-
///
25-
/// @brief This structure comprises optional function pointers used
26-
/// by corresponding umfMemoryProvider* calls. A memory provider implementation
27-
/// can keep them NULL.
28-
///
29-
typedef struct umf_memory_provider_ext_ops_0_11_t {
30-
///
31-
/// @brief Discard physical pages within the virtual memory mapping associated at the given addr
32-
/// and \p size. This call is asynchronous and may delay purging the pages indefinitely.
33-
/// @param provider pointer to the memory provider
34-
/// @param ptr beginning of the virtual memory range
35-
/// @param size size of the virtual memory range
36-
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
37-
/// UMF_RESULT_ERROR_INVALID_ALIGNMENT if ptr or size is not page-aligned.
38-
/// UMF_RESULT_ERROR_NOT_SUPPORTED if operation is not supported by this provider.
39-
///
40-
umf_result_t (*purge_lazy)(void *provider, void *ptr, size_t size);
41-
42-
///
43-
/// @brief Discard physical pages within the virtual memory mapping associated at the given addr and \p size.
44-
/// This call is synchronous and if it succeeds, pages are guaranteed to be zero-filled on the next access.
45-
/// @param provider pointer to the memory provider
46-
/// @param ptr beginning of the virtual memory range
47-
/// @param size size of the virtual memory range
48-
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure
49-
/// UMF_RESULT_ERROR_INVALID_ALIGNMENT if ptr or size is not page-aligned.
50-
/// UMF_RESULT_ERROR_NOT_SUPPORTED if operation is not supported by this provider.
51-
///
52-
umf_result_t (*purge_force)(void *provider, void *ptr, size_t size);
53-
54-
///
55-
/// @brief Merges two coarse grain allocations into a single allocation that
56-
/// can be managed (freed) as a whole.
57-
/// allocation_split and allocation_merge should be both set or both NULL.
58-
/// allocation_merge should NOT be called concurrently with allocation_split()
59-
/// with the same pointer.
60-
/// @param hProvider handle to the memory provider
61-
/// @param lowPtr pointer to the first allocation
62-
/// @param highPtr pointer to the second allocation (should be > lowPtr)
63-
/// @param totalSize size of a new merged allocation. Should be equal
64-
/// to the sum of sizes of allocations beginning at lowPtr and highPtr
65-
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure
66-
///
67-
umf_result_t (*allocation_merge)(void *hProvider, void *lowPtr,
68-
void *highPtr, size_t totalSize);
69-
70-
///
71-
/// @brief Splits a coarse grain allocation into 2 adjacent allocations that
72-
/// can be managed (freed) separately.
73-
/// allocation_split and allocation_merge should be both set or both NULL.
74-
/// allocation_split should NOT be called concurrently with allocation_merge()
75-
/// with the same pointer.
76-
/// @param hProvider handle to the memory provider
77-
/// @param ptr pointer to the beginning of the allocation
78-
/// @param totalSize total size of the allocation to be split
79-
/// @param firstSize size of the first new allocation, second allocation
80-
// has a size equal to totalSize - firstSize
81-
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure
82-
///
83-
umf_result_t (*allocation_split)(void *hProvider, void *ptr,
84-
size_t totalSize, size_t firstSize);
85-
86-
} umf_memory_provider_ext_ops_0_11_t;
87-
typedef umf_memory_provider_ext_ops_0_11_t umf_memory_provider_ext_ops_t;
88-
89-
///
90-
/// @brief This structure comprises optional IPC API. The API allows sharing of
91-
/// memory objects across different processes. A memory provider implementation can keep them NULL.
92-
///
93-
typedef struct umf_memory_provider_ipc_ops_0_11_t {
94-
///
95-
/// @brief Retrieve the size of opaque data structure required to store IPC data.
96-
/// @param provider pointer to the memory provider.
97-
/// @param size [out] pointer to the size.
98-
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
99-
/// UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
100-
umf_result_t (*get_ipc_handle_size)(void *provider, size_t *size);
101-
102-
///
103-
/// @brief Retrieve an IPC memory handle for the specified allocation.
104-
/// @param provider pointer to the memory provider.
105-
/// @param ptr beginning of the virtual memory range.
106-
/// @param size size of the memory address range.
107-
/// @param providerIpcData [out] pointer to the preallocated opaque data structure to store IPC handle.
108-
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
109-
/// UMF_RESULT_ERROR_INVALID_ARGUMENT if ptr was not allocated by this provider.
110-
/// UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
111-
umf_result_t (*get_ipc_handle)(void *provider, const void *ptr, size_t size,
112-
void *providerIpcData);
113-
114-
///
115-
/// @brief Release IPC handle retrieved with get_ipc_handle function.
116-
/// @param provider pointer to the memory provider.
117-
/// @param providerIpcData pointer to the IPC opaque data structure.
118-
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
119-
/// UMF_RESULT_ERROR_INVALID_ARGUMENT if providerIpcData was not created by this provider.
120-
/// UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
121-
umf_result_t (*put_ipc_handle)(void *provider, void *providerIpcData);
122-
123-
///
124-
/// @brief Open IPC handle.
125-
/// @param provider pointer to the memory provider.
126-
/// @param providerIpcData pointer to the IPC opaque data structure.
127-
/// @param ptr [out] pointer to the memory to be used in the current process.
128-
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
129-
/// UMF_RESULT_ERROR_INVALID_ARGUMENT if providerIpcData cannot be handled by the provider.
130-
/// UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
131-
umf_result_t (*open_ipc_handle)(void *provider, void *providerIpcData,
132-
void **ptr);
133-
134-
///
135-
/// @brief Closes an IPC memory handle.
136-
/// @param provider pointer to the memory provider.
137-
/// @param ptr pointer to the memory retrieved with open_ipc_handle function.
138-
/// @param size size of the memory address range.
139-
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
140-
/// UMF_RESULT_ERROR_INVALID_ARGUMENT if invalid \p ptr is passed.
141-
/// UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
142-
umf_result_t (*close_ipc_handle)(void *provider, void *ptr, size_t size);
143-
} umf_memory_provider_ipc_ops_0_11_t;
144-
typedef umf_memory_provider_ipc_ops_0_11_t umf_memory_provider_ipc_ops_t;
22+
#define UMF_PROVIDER_OPS_VERSION_CURRENT UMF_MAKE_VERSION(0, 12)
14523

14624
///
14725
/// @brief This structure comprises function pointers used by corresponding
14826
/// umfMemoryProvider* calls. Each memory provider implementation should
14927
/// initialize all function pointers.
15028
///
151-
typedef struct umf_memory_provider_ops_0_11_t {
29+
typedef struct umf_memory_provider_ops_t {
15230
/// Version of the ops structure.
15331
/// Should be initialized using UMF_PROVIDER_OPS_VERSION_CURRENT.
15432
uint32_t version;
15533

34+
/// Size of this structure.
35+
/// Note: Using sizeof() to get the size of this structure may return an
36+
/// invalid size due to optional functions possibly added to the "extra[]"
37+
/// variadic member.
38+
size_t size;
39+
15640
///
15741
/// @brief Initializes memory provider.
15842
/// @param params provider-specific params
@@ -244,16 +128,126 @@ typedef struct umf_memory_provider_ops_0_11_t {
244128
const char *(*get_name)(void *provider);
245129

246130
///
247-
/// @brief Optional ops
131+
/// Optional ext_* function pointers used by corresponding umfMemoryProvider*
132+
/// calls. A memory provider implementation can keep them NULL.
133+
///
134+
135+
///
136+
/// @brief Discard physical pages within the virtual memory mapping associated at the given addr
137+
/// and \p size. This call is asynchronous and may delay purging the pages indefinitely.
138+
/// @param provider pointer to the memory provider
139+
/// @param ptr beginning of the virtual memory range
140+
/// @param size size of the virtual memory range
141+
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
142+
/// UMF_RESULT_ERROR_INVALID_ALIGNMENT if ptr or size is not page-aligned.
143+
/// UMF_RESULT_ERROR_NOT_SUPPORTED if operation is not supported by this provider.
144+
///
145+
umf_result_t (*ext_purge_lazy)(void *provider, void *ptr, size_t size);
146+
147+
///
148+
/// @brief Discard physical pages within the virtual memory mapping associated at the given addr and \p size.
149+
/// This call is synchronous and if it succeeds, pages are guaranteed to be zero-filled on the next access.
150+
/// @param provider pointer to the memory provider
151+
/// @param ptr beginning of the virtual memory range
152+
/// @param size size of the virtual memory range
153+
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure
154+
/// UMF_RESULT_ERROR_INVALID_ALIGNMENT if ptr or size is not page-aligned.
155+
/// UMF_RESULT_ERROR_NOT_SUPPORTED if operation is not supported by this provider.
248156
///
249-
umf_memory_provider_ext_ops_t ext;
157+
umf_result_t (*ext_purge_force)(void *provider, void *ptr, size_t size);
250158

251159
///
252-
/// @brief Optional IPC ops. The API allows sharing of memory objects across different processes.
160+
/// @brief Merges two coarse grain allocations into a single allocation that
161+
/// can be managed (freed) as a whole.
162+
/// ext_allocation_split and allocation_merge should be both set or both NULL.
163+
/// ext_allocation_merge() should NOT be called concurrently with ext_allocation_split()
164+
/// with the same pointer.
165+
/// @param hProvider handle to the memory provider
166+
/// @param lowPtr pointer to the first allocation
167+
/// @param highPtr pointer to the second allocation (should be > lowPtr)
168+
/// @param totalSize size of a new merged allocation. Should be equal
169+
/// to the sum of sizes of allocations beginning at lowPtr and highPtr
170+
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure
171+
///
172+
umf_result_t (*ext_allocation_merge)(void *hProvider, void *lowPtr,
173+
void *highPtr, size_t totalSize);
174+
175+
///
176+
/// @brief Splits a coarse grain allocation into 2 adjacent allocations that
177+
/// can be managed (freed) separately.
178+
/// ext_allocation_split() and ext_allocation_merge() should be both set or both NULL.
179+
/// ext_allocation_split() should NOT be called concurrently with allocation_merge()
180+
/// with the same pointer.
181+
/// @param hProvider handle to the memory provider
182+
/// @param ptr pointer to the beginning of the allocation
183+
/// @param totalSize total size of the allocation to be split
184+
/// @param firstSize size of the first new allocation, second allocation
185+
// has a size equal to totalSize - firstSize
186+
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure
187+
///
188+
umf_result_t (*ext_allocation_split)(void *hProvider, void *ptr,
189+
size_t totalSize, size_t firstSize);
190+
191+
///
192+
/// Optional IPC API. The API allows sharing of memory objects across
193+
/// different processes. All ipc_* functions alre optional and a memory
194+
/// provider implementation can keep them NULL.
195+
///
196+
197+
///
198+
/// @brief Retrieve the size of opaque data structure required to store IPC data.
199+
/// @param provider pointer to the memory provider.
200+
/// @param size [out] pointer to the size.
201+
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
202+
/// UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
203+
umf_result_t (*ipc_get_handle_size)(void *provider, size_t *size);
204+
205+
///
206+
/// @brief Retrieve an IPC memory handle for the specified allocation.
207+
/// @param provider pointer to the memory provider.
208+
/// @param ptr beginning of the virtual memory range.
209+
/// @param size size of the memory address range.
210+
/// @param providerIpcData [out] pointer to the preallocated opaque data structure to store IPC handle.
211+
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
212+
/// UMF_RESULT_ERROR_INVALID_ARGUMENT if ptr was not allocated by this provider.
213+
/// UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
214+
umf_result_t (*ipc_get_handle)(void *provider, const void *ptr, size_t size,
215+
void *providerIpcData);
216+
217+
///
218+
/// @brief Release IPC handle retrieved with ipc_get_handle function.
219+
/// @param provider pointer to the memory provider.
220+
/// @param providerIpcData pointer to the IPC opaque data structure.
221+
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
222+
/// UMF_RESULT_ERROR_INVALID_ARGUMENT if providerIpcData was not created by this provider.
223+
/// UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
224+
umf_result_t (*ipc_put_handle)(void *provider, void *providerIpcData);
225+
226+
///
227+
/// @brief Open IPC handle.
228+
/// @param provider pointer to the memory provider.
229+
/// @param providerIpcData pointer to the IPC opaque data structure.
230+
/// @param ptr [out] pointer to the memory to be used in the current process.
231+
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
232+
/// UMF_RESULT_ERROR_INVALID_ARGUMENT if providerIpcData cannot be handled by the provider.
233+
/// UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
234+
umf_result_t (*ipc_open_handle)(void *provider, void *providerIpcData,
235+
void **ptr);
236+
237+
///
238+
/// @brief Closes an IPC memory handle.
239+
/// @param provider pointer to the memory provider.
240+
/// @param ptr pointer to the memory retrieved with ipc_open_handle function.
241+
/// @param size size of the memory address range.
242+
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
243+
/// UMF_RESULT_ERROR_INVALID_ARGUMENT if invalid \p ptr is passed.
244+
/// UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
245+
umf_result_t (*ipc_close_handle)(void *provider, void *ptr, size_t size);
246+
253247
///
254-
umf_memory_provider_ipc_ops_t ipc;
255-
} umf_memory_provider_ops_0_11_t;
256-
typedef umf_memory_provider_ops_0_11_t umf_memory_provider_ops_t;
248+
/// @brief Extra function pointers for future extensions.
249+
void *extra[];
250+
} umf_memory_provider_ops_t;
257251

258252
#ifdef __cplusplus
259253
}

‎src/cpp_helpers.hpp

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -89,15 +89,15 @@ template <typename T> constexpr umf_memory_provider_ops_t providerOpsBase() {
8989
UMF_ASSIGN_OP(ops, T, get_recommended_page_size, UMF_RESULT_ERROR_UNKNOWN);
9090
UMF_ASSIGN_OP(ops, T, get_min_page_size, UMF_RESULT_ERROR_UNKNOWN);
9191
UMF_ASSIGN_OP(ops, T, get_name, "");
92-
UMF_ASSIGN_OP(ops.ext, T, purge_lazy, UMF_RESULT_ERROR_UNKNOWN);
93-
UMF_ASSIGN_OP(ops.ext, T, purge_force, UMF_RESULT_ERROR_UNKNOWN);
94-
UMF_ASSIGN_OP(ops.ext, T, allocation_merge, UMF_RESULT_ERROR_UNKNOWN);
95-
UMF_ASSIGN_OP(ops.ext, T, allocation_split, UMF_RESULT_ERROR_UNKNOWN);
96-
UMF_ASSIGN_OP(ops.ipc, T, get_ipc_handle_size, UMF_RESULT_ERROR_UNKNOWN);
97-
UMF_ASSIGN_OP(ops.ipc, T, get_ipc_handle, UMF_RESULT_ERROR_UNKNOWN);
98-
UMF_ASSIGN_OP(ops.ipc, T, put_ipc_handle, UMF_RESULT_ERROR_UNKNOWN);
99-
UMF_ASSIGN_OP(ops.ipc, T, open_ipc_handle, UMF_RESULT_ERROR_UNKNOWN);
100-
UMF_ASSIGN_OP(ops.ipc, T, close_ipc_handle, UMF_RESULT_ERROR_UNKNOWN);
92+
UMF_ASSIGN_OP(ops, T, ext_purge_lazy, UMF_RESULT_ERROR_UNKNOWN);
93+
UMF_ASSIGN_OP(ops, T, ext_purge_force, UMF_RESULT_ERROR_UNKNOWN);
94+
UMF_ASSIGN_OP(ops, T, ext_allocation_merge, UMF_RESULT_ERROR_UNKNOWN);
95+
UMF_ASSIGN_OP(ops, T, ext_allocation_split, UMF_RESULT_ERROR_UNKNOWN);
96+
UMF_ASSIGN_OP(ops, T, ipc_get_handle_size, UMF_RESULT_ERROR_UNKNOWN);
97+
UMF_ASSIGN_OP(ops, T, ipc_get_handle, UMF_RESULT_ERROR_UNKNOWN);
98+
UMF_ASSIGN_OP(ops, T, ipc_put_handle, UMF_RESULT_ERROR_UNKNOWN);
99+
UMF_ASSIGN_OP(ops, T, ipc_open_handle, UMF_RESULT_ERROR_UNKNOWN);
100+
UMF_ASSIGN_OP(ops, T, ipc_close_handle, UMF_RESULT_ERROR_UNKNOWN);
101101
return ops;
102102
}
103103
} // namespace detail

0 commit comments

Comments
 (0)