[umalloc] Formalise the user memory allocation API
[people/asdlkf/gpxe.git] / src / include / gpxe / umalloc.h
1 #ifndef _GPXE_UMALLOC_H
2 #define _GPXE_UMALLOC_H
3
4 /**
5  * @file
6  *
7  * User memory allocation
8  *
9  */
10
11 #include <gpxe/api.h>
12 #include <config/umalloc.h>
13 #include <gpxe/uaccess.h>
14
15 /**
16  * Provide a user memory allocation API implementation
17  *
18  * @v _prefix           Subsystem prefix
19  * @v _api_func         API function
20  * @v _func             Implementing function
21  */
22 #define PROVIDE_UMALLOC( _subsys, _api_func, _func ) \
23         PROVIDE_SINGLE_API ( UMALLOC_PREFIX_ ## _subsys, _api_func, _func )
24
25 /* Include all architecture-independent I/O API headers */
26
27 /* Include all architecture-dependent I/O API headers */
28 #include <bits/umalloc.h>
29
30 /**
31  * Reallocate external memory
32  *
33  * @v userptr           Memory previously allocated by umalloc(), or UNULL
34  * @v new_size          Requested size
35  * @ret userptr         Allocated memory, or UNULL
36  *
37  * Calling realloc() with a new size of zero is a valid way to free a
38  * memory block.
39  */
40 userptr_t urealloc ( userptr_t userptr, size_t new_size );
41
42 /**
43  * Allocate external memory
44  *
45  * @v size              Requested size
46  * @ret userptr         Memory, or UNULL
47  *
48  * Memory is guaranteed to be aligned to a page boundary.
49  */
50 static inline __always_inline userptr_t umalloc ( size_t size ) {
51         return urealloc ( UNULL, size );
52 }
53
54 /**
55  * Free external memory
56  *
57  * @v userptr           Memory allocated by umalloc(), or UNULL
58  *
59  * If @c ptr is UNULL, no action is taken.
60  */
61 static inline __always_inline void ufree ( userptr_t userptr ) {
62         urealloc ( userptr, 0 );
63 }
64
65 #endif /* _GPXE_UMALLOC_H */