qnx/src/ipc3x_dev/ti/syslink/utils/Memory.h

   1 /**
   2  *  @file   Memory.h
   3  *
   4  *  @brief      Memory manager interface definitions.
   5  *
   6  *              This abstracts the Memory management interface to be used with
   7  *              Ipc code. Allocation, Freeing-up, copy and address translate
   8  *              are supported for the memory management.
   9  *
  10  *
  11  *  @ver        02.00.00.46_alpha1
  12  *
  13  *  ============================================================================
  14  *
  15  *  Copyright (c) 2008-2015, Texas Instruments Incorporated
  16  *
  17  *  Redistribution and use in source and binary forms, with or without
  18  *  modification, are permitted provided that the following conditions
  19  *  are met:
  20  *
  21  *  *  Redistributions of source code must retain the above copyright
  22  *     notice, this list of conditions and the following disclaimer.
  23  *
  24  *  *  Redistributions in binary form must reproduce the above copyright
  25  *     notice, this list of conditions and the following disclaimer in the
  26  *     documentation and/or other materials provided with the distribution.
  27  *
  28  *  *  Neither the name of Texas Instruments Incorporated nor the names of
  29  *     its contributors may be used to endorse or promote products derived
  30  *     from this software without specific prior written permission.
  31  *
  32  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  33  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  34  *  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  35  *  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  36  *  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  37  *  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  38  *  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  39  *  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  40  *  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  41  *  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  42  *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  43  *  Contact information for paper mail:
  44  *  Texas Instruments
  45  *  Post Office Box 655303
  46  *  Dallas, Texas 75265
  47  *  Contact information:
  48  *  http://www-k.ext.ti.com/sc/technical-support/product-information-centers.htm?
  49  *  DCMP=TIHomeTracking&HQS=Other+OT+home_d_contact
  50  *  ============================================================================
  51  *
  52  */
  53
  54
  55 #ifndef MEMORY_H_0xC97E
  56 #define MEMORY_H_0xC97E
  57
  58
  59 /* OSAL and utils */
  60 #include <ti/syslink/utils/MemoryDefs.h>
  61 #include <ti/syslink/utils/MemoryOS.h>
  62
  63 /* Module headers */
  64 #include <ti/syslink/utils/IHeap.h>
  65
  66
  67 #if defined (__cplusplus)
  68 extern "C" {
  69 #endif
  70
  71
  72 /* =============================================================================
  73  * Macros
  74  * =============================================================================
  75  */
  76 /*!
  77  *  @brief   Blocking quality
  78  *           Heaps with this "quality" may cause the calling thread to block;
  79  *           i.e., suspend execution until another thread leaves the gate.
  80  */
  81 #define Memory_Q_BLOCKING 1
  82
  83 /* =============================================================================
  84  * Structures & Enums. See MemoryDefs.h
  85  * =============================================================================
  86  */
  87
  88 /* =============================================================================
  89  *  APIs
  90  * =============================================================================
  91  */
  92 /*!
  93  *  @brief      Allocates the specified number of bytes.
  94  *
  95  *  @param      heap    Handle to the heap from which the memory is to be
  96  *                      allocated. Specify NULL to allocate from local memory.
  97  *  @param      size    Amount of memory to be allocated.
  98  *  @param      align   Alignment constraints (power of 2)
  99  *  @param      eb      Not used. Pass as NULL.
 100  *
 101  *  @retval     Pointer Success: Pointer to allocated buffer
 102  *  @retval     NULL    Failed to allocate memory
 103  *
 104  *  @sa         Memory_calloc
 105  */
 106 Ptr Memory_alloc (IHeap_Handle heap, SizeT size, SizeT align, Ptr eb);
 107
 108 /*!
 109  *  @brief      Allocates the specified number of bytes and memory is set to
 110  *              zero.
 111  *
 112  *  @param      heap    Handle to the heap from which the memory is to be
 113  *                      allocated. Specify NULL to allocate from local memory.
 114  *  @param      size    Amount of memory to be allocated.
 115  *  @param      align   Alignment constraints (power of 2)
 116  *  @param      eb      Not used. Pass as NULL.
 117  *
 118  *  @retval     Pointer Success: Pointer to allocated buffer
 119  *  @retval     NULL    Failed to allocate memory
 120  *
 121  *  @sa         Memory_alloc, MemoryOS_calloc
 122  */
 123 Ptr Memory_calloc (IHeap_Handle heap, SizeT size, SizeT align, Ptr eb);
 124
 125 /*!
 126  *  @brief      Frees up the specified chunk of memory.
 127  *
 128  *  @param      heap    Handle to the heap
 129  *  @param      block   Block of memory to be freed
 130  *  @param      size    Amount of memory to be freed
 131  *
 132  *  @sa         IHeap_free, MemoryOS_free
 133  */
 134 Void Memory_free (IHeap_Handle heap, Ptr block, SizeT size);
 135
 136 /*!
 137  *  @brief      Function to obtain statistics from a heap.
 138  *
 139  *  @param      heap    Handle to the heap
 140  *  @param      stats   Pointer to the Memory stats structure to be filled.
 141  *
 142  *  @sa
 143  */
 144 Void Memory_getStats (IHeap_Handle heap, Memory_Stats * stats);
 145
 146 /*!
 147  *  @brief      Function to test for a particular IHeap quality
 148  *
 149  *  @param      heap    Handle to the heap
 150  *  @param      qual    Quality to be queried.
 151  *
 152  *  @sa         Memory_Q_BLOCKING
 153  */
 154 Bool Memory_query (IHeap_Handle heap, Int qual);
 155
 156 /*!
 157  *  @brief      Function to get memory alignment
 158  *
 159  *  @retval     Alignment Maximum default alignment
 160  */
 161 SizeT Memory_getMaxDefaultTypeAlign (Void);
 162
 163 /*!
 164  *  @brief      Allocates the specified number of bytes and memory is set to
 165  *              the specified value.
 166  *
 167  *  @param      heap    Handle to the heap from which the memory is to be
 168  *                      allocated. Specify NULL to allocate from local memory.
 169  *  @param      size    Amount of memory to be allocated.
 170  *  @param      align   Alignment constraints (power of 2)
 171  *  @param      value   Value to be set for all bytes in the buffer
 172  *  @param      eb      Not used. Pass as NULL.
 173  *
 174  *  @retval     Pointer Success: Pointer to allocated buffer
 175  *  @retval     NULL    Failed to allocate memory
 176  *
 177  *  @sa         Memory_alloc, MemoryOS_calloc
 178  */
 179 Ptr Memory_valloc (IHeap_Handle heap,
 180                    SizeT        size,
 181                    SizeT        align,
 182                    Char         value,
 183                    Ptr          eb);
 184
 185 /*!
 186  *  @brief      Function to translate an address.
 187  *
 188  *  @param      srcAddr  source address.
 189  *  @param      flags    Tranlation flags.
 190  *
 191  *  @retval     Pointer Success: Pointer to translated buffer
 192  *  @retval     NULL    Failed to translate
 193  */
 194 Ptr Memory_translate (Ptr srcAddr, Memory_XltFlags flags);
 195
 196
 197 /* =============================================================================
 198  *  APIs that are added for MemoryOS
 199  * =============================================================================
 200  */
 201 /*!
 202  *  @brief      Maps a memory area into virtual space.
 203  *  @sa         Memory_unmap
 204  */
 205 #define Memory_map           MemoryOS_map
 206
 207 /*!
 208  *  @brief      Unmaps a memory area into virtual space.
 209  *  @sa         Memory_unmap
 210  */
 211 #define Memory_unmap         MemoryOS_unmap
 212
 213 /*!
 214  *  @brief      Copies the data between memory areas.
 215  */
 216 #define Memory_copy          MemoryOS_copy
 217
 218 /*!
 219  *  @brief      Set the specific value in the said memory area.
 220  */
 221 #define Memory_set           MemoryOS_set
 222
 223
 224 #if defined (__cplusplus)
 225 }
 226 #endif /* defined (__cplusplus) */
 227
 228 #endif /* ifndef MEMORY_H_0xC97E */