1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright (c) Intel Corporation. 3 * All rights reserved. 4 */ 5 6 #ifndef FTL_MEMPOOL_H 7 #define FTL_MEMPOOL_H 8 9 #include "spdk/stdinc.h" 10 11 #include "ftl_df.h" 12 13 /* TODO: Consider porting this mempool to general SPDK utils */ 14 15 /** 16 * @brief Creates and initializes custom FTL memory pool using DMA kind memory 17 * 18 * @param count Count of element in the memory pool 19 * @param size Size of elements in the memory pool 20 * @param alignment Memory alignment of element in the memory pool 21 * @param socket_id It is the socket identifier in the case of NUMA. The value 22 * can be *SOCKET_ID_ANY* if there is no NUMA constraint for the reserved zone. 23 * 24 * @return Pointer to the memory pool 25 */ 26 struct ftl_mempool *ftl_mempool_create(size_t count, size_t size, 27 size_t alignment, int socket_id); 28 29 /** 30 * @brief Destroys the FTL memory pool 31 32 * @param mpool The memory pool to be destroyed 33 */ 34 void ftl_mempool_destroy(struct ftl_mempool *mpool); 35 36 /** 37 * @brief Gets (allocates) an element from the memory pool 38 * 39 * Allowed only for the initialized memory pool. 40 * 41 * @param mpool The memory pool 42 * 43 * @return Element from memory pool. If memory pool empty it returns NULL. 44 */ 45 void *ftl_mempool_get(struct ftl_mempool *mpool); 46 47 /** 48 * @brief Puts (releases) the element to the memory pool 49 * 50 * Allowed only for the initialized memory pool. 51 * 52 * @param mpool The memory pool 53 * @param element The element to be released 54 */ 55 void ftl_mempool_put(struct ftl_mempool *mpool, void *element); 56 57 /** 58 * @brief Creates custom FTL memory pool using memory allocated externally 59 * 60 * The pool is uninitialized. 61 * The uninitialized pool is accessible via ftl_mempool_claim_df() and 62 * ftl_mempool_release_df() APIs. The pool's free buffer list is initialized 63 * to contain only elements that were not claimed using ftl_mempool_claim_df() 64 * after the call to ftl_mempool_initialize_ext. 65 * See ftl_mempool_initialize_ext(). 66 * 67 * @param buffer Externally allocated underlying memory buffer 68 * @param count Count of element in the memory pool 69 * @param size Size of elements in the memory pool 70 * @param alignment Memory alignment of element in the memory pool 71 * 72 * @return Pointer to the memory pool 73 */ 74 struct ftl_mempool *ftl_mempool_create_ext(void *buffer, size_t count, size_t size, 75 size_t alignment); 76 77 /** 78 * @brief Destroys the FTL memory pool w/ externally allocated underlying mem buf 79 * 80 * The external buf is not being freed. 81 * 82 * @param mpool The memory pool to be destroyed 83 */ 84 void ftl_mempool_destroy_ext(struct ftl_mempool *mpool); 85 86 /** 87 * @brief Initialize the FTL memory pool w/ externally allocated mem buf. 88 * 89 * The pool is initialized to contain only elements that were not claimed. 90 * All claimed elements are considered to be in use and will be returned 91 * to the pool via ftl_mempool_put() after initialization. 92 * After the pool is initialized, it is only accessible via 93 * ftl_mempool_get() and ftl_mempool_put() APIs. 94 * 95 * This function should only be called on an uninitialized pool (ie. created via ftl_mempool_create_ext). 96 * Any attempt to initialize an already initialized pool (whether after calling ftl_mempool_create, or 97 * calling ftl_mempool_initialize_ext twice) will result in an assert. 98 * 99 * Depending on the memory pool being initialized or not, the use of the 100 * following APIs is as follows: 101 * API uninitialized pool initialized pool 102 * ftl_mempool_get() disallowed allowed 103 * ftl_mempool_put() disallowed allowed 104 * ftl_mempool_claim_df() allowed disallowed 105 * ftl_mempool_release_df() allowed disallowed 106 * 107 * @param mpool The memory pool 108 */ 109 void ftl_mempool_initialize_ext(struct ftl_mempool *mpool); 110 111 /** 112 * @brief Return a df object id for a given pool element. 113 * 114 * @param mpool The memory pool 115 * @param df_obj_ptr Pointer to the pool element 116 * 117 * @return df object id 118 */ 119 ftl_df_obj_id ftl_mempool_get_df_obj_id(struct ftl_mempool *mpool, void *df_obj_ptr); 120 121 /** 122 * @brief Return an element pointer for a given df object id. 123 * 124 * @param mpool The memory pool 125 * @param df_obj_id Df object id of a pool element 126 * 127 * @return Element ptr 128 */ 129 void *ftl_mempool_get_df_ptr(struct ftl_mempool *mpool, ftl_df_obj_id df_obj_id); 130 131 /** 132 * @brief Claim an element for use. 133 * 134 * Allowed only for the uninitialized memory pool. 135 * 136 * @param mpool The memory pool 137 * @param df_obj_id Df object id of a pool element to claim 138 * 139 * @return Element ptr 140 */ 141 void *ftl_mempool_claim_df(struct ftl_mempool *mpool, ftl_df_obj_id df_obj_id); 142 143 /** 144 * @brief Release an element to the pool. 145 * 146 * Allowed only for the uninitialized memory pool. 147 * 148 * @param mpool The memory pool 149 * @param df_obj_id Df object id of a pool element to claim 150 */ 151 void ftl_mempool_release_df(struct ftl_mempool *mpool, ftl_df_obj_id df_obj_id); 152 153 /** 154 * @brief Return an index for a given element in the memory pool. 155 * 156 * @param mpool The memory pool 157 * @param df_obj_ptr Element from df memory pool. The pointer may be offset from the beginning of the element. 158 * 159 * @return Index (offset / element_size) of the element parameter from the beginning of the pool 160 */ 161 size_t ftl_mempool_get_df_obj_index(struct ftl_mempool *mpool, void *df_obj_ptr); 162 #endif /* FTL_MEMPOOL_H */ 163