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-2006 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) 2018 Triad National Security, LLC. All rights 14 * reserved. 15 * $COPYRIGHT$ 16 * 17 * Additional copyrights may follow 18 * 19 * $HEADER$ 20 */ 21 22 /** 23 * @file@ 24 * 25 * Hooks for receiving callbacks when memory is allocated or deallocated 26 * 27 * Hooks for receiving callbacks when memory is allocated or 28 * deallocated from the current process. Intended to be used with 29 * RDMA communication devices that require "pinning" of virtual 30 * memory. The hooks allow for a "lazy unpinning" approach, which 31 * provides better latency when application buffer reuse is high. 32 * Most operating systems do not respond well to memory being freed 33 * from a process while still pinned, so some type of callback to 34 * unpin is necessary before the memory is returned to the OS. 35 * 36 * \note For linking reasons, this is not a component framework (some of 37 * these require tight coupling into libopal and the wrapper compilers 38 * and that entire stack). 39 */ 40 41 #ifndef OPAL_MEMORY_MEMORY_H 42 #define OPAL_MEMORY_MEMORY_H 43 44 #include "opal_config.h" 45 #include "memory_internal.h" 46 47 BEGIN_C_DECLS 48 49 50 /** 51 * Initialize the memory hooks subsystem 52 * 53 * Initialize the memory hooks subsystem. This is generally called 54 * during opal_init() and should be called before any other function 55 * in the interface is called. 56 * 57 * \note Note that some back-end functionality is activated pre-main, 58 * so not calling this function does not prevent the memory hooks from 59 * becoming active. 60 * 61 * @retval OPAL_SUCCESS Initialization completed successfully 62 */ 63 OPAL_DECLSPEC int opal_mem_hooks_init(void); 64 65 66 /** 67 * Query level of support provided by memory hooks 68 * 69 * Query memory hooks subsystem about the level of support provided by 70 * the current system configuration. The return value is \c 0 if no 71 * support is provided or a bit-wise OR of the available return values 72 * if support is provided. 73 * 74 * @retval OPAL_MEMORY_FREE_SUPPORT Memory hooks subsytem can trigger 75 * callback events when memory is going 76 * to be released by the process, either 77 * by the user calling an allocator 78 * function or munmap. Implies 79 * OPAL_MEMORY_MUNMAP_SUPPORT. 80 * @retval OPAL_MEMORY_MUNMAP_SUPPORT Subsystem can trigger callback events 81 * by the user calling munmap directly. 82 * @retval OPAL_MEMORY_CHUNK_SUPPORT Memory hooks subsystem will only 83 * trigger callback events when the 84 * process is giving memory back to the 85 * operating system, not at ever call 86 * to realloc/free/etc. 87 * 88 * \note This function must be called after opal_mem_hooks_init(). 89 */ 90 OPAL_DECLSPEC int opal_mem_hooks_support_level(void); 91 92 93 /** 94 * Memory status change callback 95 * 96 * Typedef for callbacks triggered when memory has been allocated or 97 * is about to be freed. The callback will be triggered according to 98 * the note in opal_mem_hooks_register_alloc() or 99 * opal_mem_hooks_register_release(). 100 * 101 * @param buf Pointer to the start of the allocation 102 * @param lentgh Length of the allocation 103 * @param cbdata Data passed to memory hooks when callback 104 * was registered 105 * @param from_alloc True if the callback is caused by a call to the 106 * general allocation routines (malloc, calloc, free, 107 * etc.) or directly from the user (mmap, munmap, etc.) 108 */ 109 typedef void (opal_mem_hooks_callback_fn_t)(void *buf, size_t length, 110 void *cbdata, bool from_alloc); 111 112 113 /** 114 * Register callback for when memory is to be released 115 * 116 * Register a \c opal_mem_hooks_callback_fn_t function pointer to be called 117 * whenever the current process is about to release memory. 118 * 119 * @param func Function pointer to call when memory is to be released 120 * @param cbdata A pointer-length field to be passed to func when it is 121 * invoked. 122 * 123 * @retval OPAL_SUCCESS The registration completed successfully. 124 * @retval OPAL_EXISTS The function is already registered and will not 125 * be registered again. 126 * @retval OPAL_ERR_NOT_SUPPORTED There are no hooks available for 127 * receiving callbacks when memory is to be released 128 */ 129 OPAL_DECLSPEC int opal_mem_hooks_register_release(opal_mem_hooks_callback_fn_t *func, 130 void *cbdata); 131 132 /** 133 * Unregister previously registered release callback 134 * 135 * Unregister previously registered release callback. 136 * 137 * @param func Function pointer to registered callback to remove 138 * 139 * @retval OPAL_SUCCESS The function was successfully deregistered 140 * @retval OPAL_ERR_NOT_FOUND The function was not previously registered 141 */ 142 OPAL_DECLSPEC int opal_mem_hooks_unregister_release(opal_mem_hooks_callback_fn_t *func); 143 144 145 END_C_DECLS 146 147 #endif /* OPAL_MEMORY_MEMORY_H */