1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
2 /*
3 * Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
4 * University Research and Technology
5 * Corporation. All rights reserved.
6 * Copyright (c) 2004-2007 The University of Tennessee and The University
7 * of Tennessee Research Foundation. All rights
8 * reserved.
9 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
10 * University of Stuttgart. All rights reserved.
11 * Copyright (c) 2004-2005 The Regents of the University of California.
12 * All rights reserved.
13 * Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.
14 * Copyright (c) 2011 NVIDIA Corporation. All rights reserved.
15 * Copyright (c) 2015 Los Alamos National Security, LLC. All rights
16 * reserved.
17 * $COPYRIGHT$
18 *
19 * Additional copyrights may follow
20 *
21 * $HEADER$
22 */
23 /**
24 * @file
25 * Description of the Memory Pool framework
26 */
27 #ifndef MCA_MPOOL_H
28 #define MCA_MPOOL_H
29 #include "opal_config.h"
30 #include "opal/mca/mca.h"
31 #include "opal/class/opal_free_list.h"
32 #include "opal/mca/rcache/base/rcache_base_vma.h"
33
34 #include "opal/mca/crs/crs.h"
35 #include "opal/mca/crs/base/base.h"
36
37 #define MCA_MPOOL_ALLOC_FLAG_DEFAULT 0x00
38 #define MCA_MPOOL_ALLOC_FLAG_USER 0x01
39
40 #define MCA_MPOOL_FLAGS_MPI_ALLOC_MEM 0x80
41
42 struct opal_info_t;
43 struct mca_mpool_base_module_t;
44 typedef struct mca_mpool_base_module_t mca_mpool_base_module_t;
45
46 /**
47 * component query function
48 *
49 * @param[in] hints memory pool hints in order of priority. this should
50 * be replaced by opal_info_t when the work to move
51 * info down to opal is complete.
52 * @param[out] priority relative priority of this memory pool component
53 * @param[out] module best match module
54 *
55 * This function should parse the provided hints and return a relative priority
56 * of the component based on the number of hints matched. For example, if the
57 * hints are "page_size=2M,high-bandwidth" and a pool matches the page_size but
58 * not the high-bandwidth hint then the component should return a lower priority
59 * than if both matched but a higher priority than if a pool matches only the
60 * high-bandwidth hint.
61 *
62 * Memory pools should try to support at a minimum name=value but can define
63 * any additional keys.
64 */
65 typedef int (*mca_mpool_base_component_query_fn_t) (const char *hints, int *priority,
66 mca_mpool_base_module_t **module);
67
68 /**
69 * allocate function typedef
70 */
71 typedef void *(*mca_mpool_base_module_alloc_fn_t) (mca_mpool_base_module_t *mpool,
72 size_t size, size_t align,
73 uint32_t flags);
74
75 /**
76 * allocate function typedef
77 */
78 typedef void *(*mca_mpool_base_module_realloc_fn_t) (mca_mpool_base_module_t *mpool,
79 void *addr, size_t size);
80
81 /**
82 * free function typedef
83 */
84 typedef void (*mca_mpool_base_module_free_fn_t) (mca_mpool_base_module_t *mpool,
85 void *addr);
86
87 /**
88 * if appropriate - returns base address of memory pool
89 */
90 typedef void* (*mca_mpool_base_module_address_fn_t) (mca_mpool_base_module_t *mpool);
91
92 /**
93 * finalize
94 */
95 typedef void (*mca_mpool_base_module_finalize_fn_t)(mca_mpool_base_module_t *mpool);
96
97
98 /**
99 * Fault Tolerance Event Notification Function
100 * @param state Checkpoint Stae
101 * @return OPAL_SUCCESS or failure status
102 */
103 typedef int (*mca_mpool_base_module_ft_event_fn_t)(int state);
104
105
106 /**
107 * mpool component descriptor. Contains component version information
108 * and open/close/init functions.
109 */
110 struct mca_mpool_base_component_2_0_0_t {
111 mca_base_component_t mpool_version; /**< version */
112 mca_base_component_data_t mpool_data;/**< metadata */
113
114 mca_mpool_base_component_query_fn_t mpool_query; /**< query for matching pools */
115 };
116 /**
117 * Convenience typedef.
118 */
119 typedef struct mca_mpool_base_component_2_0_0_t mca_mpool_base_component_2_0_0_t;
120 /**
121 * Convenience typedef
122 */
123 typedef struct mca_mpool_base_component_2_0_0_t mca_mpool_base_component_t;
124
125 /**
126 * mpool module descriptor. Contains the interface functions exported
127 * by the component. This does not expose memory management
128 * details.
129 */
130 struct mca_mpool_base_module_t {
131 mca_mpool_base_component_t *mpool_component; /**< component stuct */
132 mca_mpool_base_module_address_fn_t mpool_base; /**< returns the base address */
133 mca_mpool_base_module_alloc_fn_t mpool_alloc; /**< allocate function */
134 mca_mpool_base_module_realloc_fn_t mpool_realloc; /**< reallocate function */
135 mca_mpool_base_module_free_fn_t mpool_free; /**< free function */
136
137 mca_mpool_base_module_finalize_fn_t mpool_finalize; /**< finalize */
138 mca_mpool_base_module_ft_event_fn_t mpool_ft_event; /**< ft_event */
139 uint32_t flags; /**< mpool flags */
140
141 size_t mpool_allocation_unit; /**< allocation unit used by this mpool */
142 char *mpool_name; /**< name of this pool module */
143 };
144
145
146 /**
147 * Function to allocate special memory according to what the user requests in
148 * the info object.
149 *
150 * If the user passes in a valid info structure then the function will
151 * try to allocate the memory and register it with every mpool that there is a
152 * key for it in the info struct. If it fails at registering the memory with
153 * one of the requested mpools, an error will be returned. Also, if there is a
154 * key in info that does not match any mpool, an error will be returned.
155 *
156 * If the info parameter is MPI_INFO_NULL, then this function will try to allocate
157 * the memory and register it wih as many mpools as possible. However,
158 * if any of the registratons fail the mpool will simply be ignored.
159 *
160 * @param size the size of the memory area to allocate
161 * @param info an info object which tells us what kind of memory to allocate
162 *
163 * @retval pointer to the allocated memory
164 * @retval NULL on failure
165 */
166 OPAL_DECLSPEC void * mca_mpool_base_alloc(size_t size, struct opal_info_t * info, const char *hints);
167
168 /**
169 * Function to free memory previously allocated by mca_mpool_base_alloc
170 *
171 * @param base pointer to the memory to free
172 *
173 * @retval OPAL_SUCCESS
174 * @retval OPAL_ERR_BAD_PARAM if the passed base pointer was invalid
175 */
176 OPAL_DECLSPEC int mca_mpool_base_free(void * base);
177
178 /**
179 * Function for the red black tree to compare 2 keys
180 *
181 * @param key1 a pointer to the 1st key
182 * @param key2 a pointer to the second key
183 *
184 * @retval -1 if key1 is below key2
185 * @retval 1 if key 1 is above key2
186 * @retval 0 if the keys are the same
187 */
188 OPAL_DECLSPEC int mca_mpool_base_tree_node_compare(void * key1, void * key2);
189
190 /**
191 * Macro for use in components that are of type mpool
192 */
193 #define MCA_MPOOL_BASE_VERSION_3_0_0 \
194 OPAL_MCA_BASE_VERSION_2_1_0("mpool", 3, 0, 0)
195
196 #endif /* MCA_MPOOL_H */
197