« back to all changes in this revision
Viewing changes to src/ump.h
- browse files at revision 9
- compare with another revision
- download diff
- download tarball
- view history from revision 9
- Committer: Luc Verhaegen
- Date: 2014-03-25 21:04:12 UTC
- Revision ID: git-v1:5769ba0fa788b57cf6794561fc87cf96ae3af61d
autotool
Signed-off-by: Luc Verhaegen <libv@skynet.be>
Signed-off-by: Luc Verhaegen <libv@skynet.be>
- files added:
- src/ump.h
- files removed:
- debian
- files modified:
- Makefile.am
added
removed
src/ump.h
1
/*
2
* Copyright (C) 2010-2012 ARM Limited. All rights reserved.
3
*
4
* Licensed under the Apache License, Version 2.0 (the "License");
5
* you may not use this file except in compliance with the License.
6
* You may obtain a copy of the License at
7
*
8
* http://www.apache.org/licenses/LICENSE-2.0
9
*
10
* Unless required by applicable law or agreed to in writing, software
11
* distributed under the License is distributed on an "AS IS" BASIS,
12
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
* See the License for the specific language governing permissions and
14
* limitations under the License.
15
*/
16
17
/**
18
* @file ump.h
19
*
20
* This file contains the user space part of the UMP API.
21
*/
22
23
#ifndef _UNIFIED_MEMORY_PROVIDER_H_
24
#define _UNIFIED_MEMORY_PROVIDER_H_
25
26
27
/** @defgroup ump_user_space_api UMP User Space API
28
* @{ */
29
30
31
#include "ump_platform.h"
32
33
34
#ifdef __cplusplus
35
extern "C" {
36
#endif
37
38
39
/**
40
* External representation of a UMP handle in user space.
41
*/
42
typedef void * ump_handle;
43
44
/**
45
* Typedef for a secure ID, a system wide identificator for UMP memory buffers.
46
*/
47
typedef unsigned int ump_secure_id;
48
49
/**
50
* Value to indicate an invalid UMP memory handle.
51
*/
52
#define UMP_INVALID_MEMORY_HANDLE ((ump_handle)0)
53
54
/**
55
* Value to indicate an invalid secure Id.
56
*/
57
#define UMP_INVALID_SECURE_ID ((ump_secure_id)-1)
58
59
/**
60
* UMP error codes for user space.
61
*/
62
typedef enum
63
{
64
UMP_OK = 0, /**< indicates success */
65
UMP_ERROR, /**< indicates failure */
66
} ump_result;
67
68
69
/**
70
* Opens and initializes the UMP library.
71
*
72
* This function must be called at least once before calling any other UMP API functions.
73
* Each open is reference counted and must be matched with a call to @ref ump_close "ump_close".
74
*
75
* @see ump_close
76
*
77
* @return UMP_OK indicates success, UMP_ERROR indicates failure.
78
*/
79
UMP_API_EXPORT ump_result ump_open(void);
80
81
82
/**
83
* Terminate the UMP library.
84
*
85
* This must be called once for every successful @ref ump_open "ump_open". The UMP library is
86
* terminated when, and only when, the last open reference to the UMP interface is closed.
87
*
88
* @see ump_open
89
*/
90
UMP_API_EXPORT void ump_close(void);
91
92
93
/**
94
* Retrieves the secure ID for the specified UMP memory.
95
*
96
* This identificator is unique across the entire system, and uniquely identifies
97
* the specified UMP memory. This identificator can later be used through the
98
* @ref ump_handle_create_from_secure_id "ump_handle_create_from_secure_id" or
99
* @ref ump_dd_handle_create_from_secure_id "ump_dd_handle_create_from_secure_id"
100
* functions in order to access this UMP memory, for instance from another process.
101
*
102
* @note There is a kernel space equivalent function called @ref ump_dd_secure_id_get "ump_dd_secure_id_get"
103
*
104
* @see ump_handle_create_from_secure_id
105
* @see ump_dd_handle_create_from_secure_id
106
* @see ump_dd_secure_id_get
107
*
108
* @param mem Handle to UMP memory.
109
*
110
* @return Returns the secure ID for the specified UMP memory.
111
*/
112
UMP_API_EXPORT ump_secure_id ump_secure_id_get(ump_handle mem);
113
114
115
/**
116
* Retrieves a handle to allocated UMP memory.
117
*
118
* The usage of UMP memory is reference counted, so this will increment the reference
119
* count by one for the specified UMP memory.
120
* Use @ref ump_reference_release "ump_reference_release" when there is no longer any
121
* use for the retrieved handle.
122
*
123
* @note There is a kernel space equivalent function called @ref ump_dd_handle_create_from_secure_id "ump_dd_handle_create_from_secure_id"
124
*
125
* @see ump_reference_release
126
* @see ump_dd_handle_create_from_secure_id
127
*
128
* @param secure_id The secure ID of the UMP memory to open, that can be retrieved using the @ref ump_secure_id_get "ump_secure_id_get " function.
129
*
130
* @return UMP_INVALID_MEMORY_HANDLE indicates failure, otherwise a valid handle is returned.
131
*/
132
UMP_API_EXPORT ump_handle ump_handle_create_from_secure_id(ump_secure_id secure_id);
133
134
135
/**
136
* Retrieves the actual size of the specified UMP memory.
137
*
138
* The size is reported in bytes, and is typically page aligned.
139
*
140
* @note There is a kernel space equivalent function called @ref ump_dd_size_get "ump_dd_size_get"
141
*
142
* @see ump_dd_size_get
143
*
144
* @param mem Handle to UMP memory.
145
*
146
* @return Returns the allocated size of the specified UMP memory, in bytes.
147
*/
148
UMP_API_EXPORT unsigned long ump_size_get(ump_handle mem);
149
150
151
/**
152
* Read from specified UMP memory.
153
*
154
* Another way of reading from (and writing to) UMP memory is to use the
155
* @ref ump_mapped_pointer_get "ump_mapped_pointer_get" to retrieve
156
* a CPU mapped pointer to the memory.
157
*
158
* @see ump_mapped_pointer_get
159
*
160
* @param dst Destination buffer.
161
* @param src Handle to UMP memory to read from.
162
* @param offset Where to start reading, given in bytes.
163
* @param length How much to read, given in bytes.
164
*/
165
UMP_API_EXPORT void ump_read(void * dst, ump_handle src, unsigned long offset, unsigned long length);
166
167
168
/**
169
* Write to specified UMP memory.
170
*
171
* Another way of writing to (and reading from) UMP memory is to use the
172
* @ref ump_mapped_pointer_get "ump_mapped_pointer_get" to retrieve
173
* a CPU mapped pointer to the memory.
174
*
175
* @see ump_mapped_pointer_get
176
*
177
* @param dst Handle to UMP memory to write to.
178
* @param offset Where to start writing, given in bytes.
179
* @param src Buffer to read from.
180
* @param length How much to write, given in bytes.
181
*/
182
UMP_API_EXPORT void ump_write(ump_handle dst, unsigned long offset, const void * src, unsigned long length);
183
184
185
/**
186
* Retrieves a memory mapped pointer to the specified UMP memory.
187
*
188
* This function retrieves a memory mapped pointer to the specified UMP memory,
189
* that can be used by the CPU. Every successful call to
190
* @ref ump_mapped_pointer_get "ump_mapped_pointer_get" is reference counted,
191
* and must therefore be followed by a call to
192
* @ref ump_mapped_pointer_release "ump_mapped_pointer_release " when the
193
* memory mapping is no longer needed.
194
*
195
* @note Systems without a MMU for the CPU only return the physical address, because no mapping is required.
196
*
197
* @see ump_mapped_pointer_release
198
*
199
* @param mem Handle to UMP memory.
200
*
201
* @return NULL indicates failure, otherwise a CPU mapped pointer is returned.
202
*/
203
UMP_API_EXPORT void * ump_mapped_pointer_get(ump_handle mem);
204
205
206
/**
207
* Releases a previously mapped pointer to the specified UMP memory.
208
*
209
* The CPU mapping of the specified UMP memory memory is reference counted,
210
* so every call to @ref ump_mapped_pointer_get "ump_mapped_pointer_get" must
211
* be matched with a call to this function when the mapping is no longer needed.
212
*
213
* The CPU mapping is not removed before all references to the mapping is released.
214
*
215
* @note Systems without a MMU must still implement this function, even though no unmapping should be needed.
216
*
217
* @param mem Handle to UMP memory.
218
*/
219
UMP_API_EXPORT void ump_mapped_pointer_release(ump_handle mem);
220
221
222
/**
223
* Adds an extra reference to the specified UMP memory.
224
*
225
* This function adds an extra reference to the specified UMP memory. This function should
226
* be used every time a UMP memory handle is duplicated, that is, assigned to another ump_handle
227
* variable. The function @ref ump_reference_release "ump_reference_release" must then be used
228
* to release each copy of the UMP memory handle.
229
*
230
* @note You are not required to call @ref ump_reference_add "ump_reference_add"
231
* for UMP handles returned from
232
* @ref ump_handle_create_from_secure_id "ump_handle_create_from_secure_id",
233
* because these handles are already reference counted by this function.
234
*
235
* @note There is a kernel space equivalent function called @ref ump_dd_reference_add "ump_dd_reference_add"
236
*
237
* @see ump_dd_reference_add
238
*
239
* @param mem Handle to UMP memory.
240
*/
241
UMP_API_EXPORT void ump_reference_add(ump_handle mem);
242
243
244
/**
245
* Releases a reference from the specified UMP memory.
246
*
247
* This function should be called once for every reference to the UMP memory handle.
248
* When the last reference is released, all resources associated with this UMP memory
249
* handle are freed.
250
*
251
* @note There is a kernel space equivalent function called @ref ump_dd_reference_release "ump_dd_reference_release"
252
*
253
* @see ump_dd_reference_release
254
*
255
* @param mem Handle to UMP memory.
256
*/
257
UMP_API_EXPORT void ump_reference_release(ump_handle mem);
258
259
260
#ifdef __cplusplus
261
}
262
#endif
263
264
265
/** @} */ /* end group ump_user_space_api */
266
267
268
#endif /*_UNIFIED_MEMORY_PROVIDER_H_ */
Loggerhead is a web-based interface for Breezy
Version: 2.0.1