~thopiekar/arm-mali/libump-sunxi

« back to all changes in this revision

Viewing changes to src/ump.h

  • Committer: Luc Verhaegen
  • Date: 2014-03-25 21:04:12 UTC
  • Revision ID: git-v1:fa5ad94ac2873793dcca65dafc3ea211de5e7226
import ump r2p4 source

Signed-off-by: Luc Verhaegen <libv@skynet.be>

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
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 therefor 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_ */