src/ti/ipc/HeapBufMP.h

   1 /*
   2  * Copyright (c) 2012-2013, Texas Instruments Incorporated
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * *  Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * *  Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * *  Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32 /** ============================================================================
  33  *  @file       HeapBufMP.h
  34  *
  35  *  @brief      Multi-processor fixed-size buffer heap implementation
  36  *
  37  *  Heap implementation that manages fixed size buffers that can be used
  38  *  in a multiprocessor system with shared memory.
  39  *
  40  *  The HeapBufMP manager provides functions to allocate and free storage from a
  41  *  heap of type HeapBufMP which inherits from IHeap. HeapBufMP manages a single
  42  *  fixed-size buffer, split into equally sized allocatable blocks.
  43  *
  44  *  The HeapBufMP manager is intended as a very fast memory
  45  *  manager which can only allocate blocks of a single size. It is ideal for
  46  *  managing a heap that is only used for allocating a single type of object,
  47  *  or for objects that have very similar sizes.
  48  *
  49  *  The HeapBufMP module uses a NameServer instance to
  50  *  store instance information when an instance is created.  The name supplied
  51  *  must be unique for all HeapBufMP instances.
  52  *
  53  *  The #HeapBufMP_create call initializes the shared memory as needed. Once an
  54  *  instance is created, a #HeapBufMP_open can be performed. The
  55  *  open is used to gain access to the same HeapBufMP instance.
  56  *  Generally an instance is created on one processor and opened on the
  57  *  other processor(s).
  58  *
  59  *  The open returns a HeapBufMP instance handle like the create,
  60  *  however the open does not modify the shared memory.
  61  *
  62  *  The HeapBufMP header should be included in an application as follows:
  63  *  @code
  64  *  #include <ti/ipc/HeapBufMP.h>
  65  *  @endcode
  66  *
  67  *  @version        0.00.01
  68  */
  69
  70
  71 #ifndef ti_ipc_HeapBufMP__include
  72 #define ti_ipc_HeapBufMP__include
  73
  74 #if defined (__cplusplus)
  75 extern "C" {
  76 #endif
  77
  78 #include <ti/ipc/GateMP.h>
  79
  80 /* =============================================================================
  81  *  All success and failure codes for the module
  82  * =============================================================================
  83  */
  84
  85 /*!
  86  *  @def    HeapBufMP_S_BUSY
  87  *  @brief  The resource is still in use
  88  */
  89 #define HeapBufMP_S_BUSY               2
  90
  91 /*!
  92  *  @def    HeapBufMP_S_ALREADYSETUP
  93  *  @brief  The module has been already setup
  94  */
  95 #define HeapBufMP_S_ALREADYSETUP       1
  96
  97 /*!
  98  *  @def    HeapBufMP_S_SUCCESS
  99  *  @brief  Operation is successful.
 100  */
 101 #define HeapBufMP_S_SUCCESS            0
 102
 103 /*!
 104  *  @def    HeapBufMP_E_FAIL
 105  *  @brief  Generic failure.
 106  */
 107 #define HeapBufMP_E_FAIL              -1
 108
 109 /*!
 110  *  @def    HeapBufMP_E_INVALIDARG
 111  *  @brief  Argument passed to function is invalid.
 112  */
 113 #define HeapBufMP_E_INVALIDARG        -2
 114
 115 /*!
 116  *  @def    HeapBufMP_E_MEMORY
 117  *  @brief  Operation resulted in memory failure.
 118  */
 119 #define HeapBufMP_E_MEMORY            -3
 120
 121 /*!
 122  *  @def    HeapBufMP_E_ALREADYEXISTS
 123  *  @brief  The specified entity already exists.
 124  */
 125 #define HeapBufMP_E_ALREADYEXISTS     -4
 126
 127 /*!
 128  *  @def    HeapBufMP_E_NOTFOUND
 129  *  @brief  Unable to find the specified entity.
 130  */
 131 #define HeapBufMP_E_NOTFOUND          -5
 132
 133 /*!
 134  *  @def    HeapBufMP_E_TIMEOUT
 135  *  @brief  Operation timed out.
 136  */
 137 #define HeapBufMP_E_TIMEOUT           -6
 138
 139 /*!
 140  *  @def    HeapBufMP_E_INVALIDSTATE
 141  *  @brief  Module is not initialized.
 142  */
 143 #define HeapBufMP_E_INVALIDSTATE      -7
 144
 145 /*!
 146  *  @def    HeapBufMP_E_OSFAILURE
 147  *  @brief  A failure occurred in an OS-specific call  */
 148 #define HeapBufMP_E_OSFAILURE         -8
 149
 150 /*!
 151  *  @def    HeapBufMP_E_RESOURCE
 152  *  @brief  Specified resource is not available  */
 153 #define HeapBufMP_E_RESOURCE          -9
 154
 155 /*!
 156  *  @def    HeapBufMP_E_RESTART
 157  *  @brief  Operation was interrupted. Please restart the operation  */
 158 #define HeapBufMP_E_RESTART           -10
 159
 160 /* =============================================================================
 161  *  Structures & Enums
 162  * =============================================================================
 163  */
 164
 165 /*!
 166  *  @brief  HeapBufMP_Handle type
 167  */
 168 typedef struct HeapBufMP_Object *HeapBufMP_Handle;
 169
 170 /*!
 171  *  @brief  Structure defining parameters for the HeapBufMP module.
 172  */
 173 typedef struct HeapBufMP_Params {
 174     String name;
 175     /*!< Name of this instance.
 176      *
 177      *  The name (if not NULL) must be unique among all HeapBufMP
 178      *  instances in the entire system.  When creating a new
 179      *  heap, it is necessary to supply an instance name.
 180      *
 181      *  The name does not have to be persistent.  The supplied string is copied
 182      *  into persistent memory.
 183      */
 184
 185     UInt16 regionId;
 186     /*!< Shared region ID
 187      *
 188      *  The index corresponding to the shared region from which shared memory
 189      *  will be allocated.
 190      */
 191
 192     /*! @cond */
 193     Ptr sharedAddr;
 194     /*!< Physical address of the shared memory
 195      *
 196      *  This value can be left as 'null' unless it is required to place the
 197      *  heap at a specific location in shared memory.  If sharedAddr is null,
 198      *  then shared memory for a new instance will be allocated from the
 199      *  heap belonging to the region identified by #HeapBufMP_Params::regionId.
 200      */
 201     /*! @endcond */
 202
 203     SizeT blockSize;
 204     /*!< Size (in MAUs) of each block.
 205      *
 206      *  HeapBufMP will round the blockSize up to the nearest multiple of the
 207      *  alignment, so the actual blockSize may be larger. When creating a
 208      *  HeapBufMP dynamically, this needs to be taken into account to determine
 209      *  the proper buffer size to pass in.
 210      *
 211      *  Required parameter.
 212      *
 213      *  The default size of the blocks is 0 MAUs.
 214      */
 215
 216     UInt numBlocks;
 217     /*!<Number of fixed-size blocks.
 218      *
 219      *  This is a required parameter for all new HeapBufMP instances.
 220      */
 221
 222     SizeT align;
 223     /*!< Alignment (in MAUs) of each block.
 224      *
 225      *  The alignment must be a power of 2. If the value 0 is specified,
 226      *  the value will be changed to meet minimum structure alignment
 227      *  requirements and the cache alignment size of the region in which the
 228      *  heap will be placed.  Therefore, the actual alignment may be larger.
 229      *
 230      *  The default alignment is 0.
 231      */
 232
 233     Bool exact;
 234     /*!< Use exact matching
 235      *
 236      *  Setting this flag will allow allocation only if the requested size
 237      *  is equal to (rather than less than or equal to) the buffer's block
 238      *  size.
 239      */
 240
 241     GateMP_Handle gate;
 242     /*!< GateMP used for critical region management of the shared memory
 243      *
 244      *  Using the default value of NULL will result in use of the GateMP
 245      *  system gate for context protection.
 246      */
 247
 248 } HeapBufMP_Params;
 249
 250 /*!
 251  *  @brief  Stats structure for the HeapBufMP_getExtendedStats API.
 252  */
 253 typedef struct HeapBufMP_ExtendedStats {
 254     UInt maxAllocatedBlocks;
 255     /*!< The maximum number of blocks allocated from this heap at any point in
 256      *  time during the lifetime of this HeapBufMP instance.
 257      */
 258
 259     UInt numAllocatedBlocks;
 260     /*!< The total number of blocks currently allocated in this HeapBufMP
 261      *  instance.
 262      */
 263 } HeapBufMP_ExtendedStats;
 264
 265 /* =============================================================================
 266  *  HeapBufMP Module-wide Functions
 267  * =============================================================================
 268  */
 269
 270 /*!
 271  *  @brief      Close a HeapBufMP instance
 272  *
 273  *  Closing an instance will free local memory consumed by the opened
 274  *  instance. All opened instances should be closed before the instance
 275  *  is deleted.
 276  *
 277  *  @param[in,out]  handlePtr   Pointer to HeapBufMP handle typically returned
 278  *                              from #HeapBufMP_open
 279  *
 280  *  @return     HeapBufMP status:
 281  *              - #HeapBufMP_S_SUCCESS: Heap successfully closed
 282  *
 283  *  @sa         HeapBufMP_open
 284  */
 285 Int HeapBufMP_close(HeapBufMP_Handle *handlePtr);
 286
 287 /*!
 288  *  @brief      Create a HeapBufMP instance
 289  *
 290  *  @param[in]  params      HeapBufMP parameters
 291  *
 292  *  @return     HeapBufMP Handle
 293  */
 294 HeapBufMP_Handle HeapBufMP_create(const HeapBufMP_Params *params);
 295
 296 /*!
 297  *  @brief      Delete a created HeapBufMP instance
 298  *
 299  *  @param[in,out]  handlePtr   Pointer to handle to delete.
 300  *
 301  *  @return     HeapBufMP status:
 302  *              - #HeapBufMP_S_SUCCESS: Heap successfully deleted
 303  */
 304 Int HeapBufMP_delete(HeapBufMP_Handle *handlePtr);
 305
 306 /*!
 307  *  @brief      Open a created HeapBufMP instance
 308  *
 309  *  Once an instance is created, an open can be performed. The
 310  *  open is used to gain access to the same HeapBufMP instance.
 311  *  Generally an instance is created on one processor and opened on the
 312  *  other processor.
 313  *
 314  *  The open returns a HeapBufMP instance handle like the create,
 315  *  however the open does not initialize the shared memory. The supplied
 316  *  name is used to identify the created instance.
 317  *
 318  *  Call #HeapBufMP_close when the opened instance is not longer needed.
 319  *
 320  *  @param[in]  name        Name of created HeapBufMP instance
 321  *  @param[out] handlePtr   Pointer to HeapBufMP handle to be opened
 322  *
 323  *  @return     HeapBufMP status:
 324  *              - #HeapBufMP_S_SUCCESS: Heap successfully opened
 325  *              - #HeapBufMP_E_NOTFOUND: Heap is not yet ready to be opened.
 326  *              - #HeapBufMP_E_FAIL: A general failure has occurred
 327  *
 328  *  @sa         HeapBufMP_close
 329  */
 330 Int HeapBufMP_open(String name, HeapBufMP_Handle *handlePtr);
 331
 332 /*! @cond */
 333 Int HeapBufMP_openByAddr(Ptr sharedAddr, HeapBufMP_Handle *handlePtr);
 334
 335 /*! @endcond */
 336
 337 /*!
 338  *  @brief      Initialize a HeapBufMP parameters struct
 339  *
 340  *  @param[out] params      Pointer to GateMP parameters
 341  *
 342  */
 343 Void HeapBufMP_Params_init(HeapBufMP_Params *params);
 344
 345 /*! @cond */
 346 /*!
 347  *  @brief      Amount of shared memory required for creation of each instance
 348  *
 349  *  @param[in]  params      Pointer to the parameters that will be used in
 350  *                          the create.
 351  *
 352  *  @return     Number of MAUs needed to create the instance.
 353  */
 354 SizeT HeapBufMP_sharedMemReq(const HeapBufMP_Params *params);
 355
 356 /*! @endcond */
 357
 358 /* =============================================================================
 359  *  HeapBufMP Per-instance Functions
 360  * =============================================================================
 361  */
 362
 363 /*!
 364  *  @brief      Allocate a block of memory of specified size and alignment
 365  *
 366  *  The actual block returned may be larger than requested to satisfy
 367  *  alignment requirements. NULL is returned if alloc fails.
 368  *
 369  *  HeapBufMP_alloc will lock the heap using the HeapBufMP gate
 370  *  while it traverses the list of free blocks to find a large enough block
 371  *  for the request.
 372  *
 373  *  Guidelines for using large heaps and multiple alloc() calls.
 374  *      - If possible, allocate larger blocks first. Previous allocations
 375  *        of small memory blocks can reduce the size of the blocks
 376  *        available for larger memory allocations.
 377  *      - Realize that alloc() can fail even if the heap contains a
 378  *        sufficient absolute amount of unalloccated space. This is
 379  *        because the largest free memory block may be smaller than
 380  *        total amount of unallocated memory.
 381  *
 382  *  @param[in]  handle    Handle to previously created/opened instance.
 383  *  @param[in]  size      Size to be allocated (in MADUs)
 384  *  @param[in]  align     Alignment for allocation (power of 2)
 385  *
 386  *  @sa         HeapBufMP_free
 387  */
 388 Void *HeapBufMP_alloc(HeapBufMP_Handle handle, SizeT size, SizeT align);
 389
 390 /*!
 391  *  @brief      Frees a block of memory.
 392  *
 393  *  free() places the memory block specified by addr and size back into the
 394  *  free pool of the heap specified. The newly freed block is combined with
 395  *  any adjacent free blocks. The space is then available for further
 396  *  allocation by alloc().
 397  *
 398  *  #HeapBufMP_free will lock the heap using the HeapBufMP gate if one is
 399  *  specified or the system GateMP if not.
 400  *
 401  *  @param[in]  handle    Handle to previously created/opened instance.
 402  *  @param[in]  block     Block of memory to be freed.
 403  *  @param[in]  size      Size to be freed (in MADUs)
 404  *
 405  *  @sa         HeapBufMP_alloc
 406  */
 407 Void HeapBufMP_free(HeapBufMP_Handle handle, Ptr block, SizeT size);
 408
 409 /*!
 410  *  @brief      Get extended memory statistics
 411  *
 412  *  This function retrieves the extended statistics for a HeapBufMP
 413  *  instance.  It does not retrieve the standard Memory_Stats
 414  *  information.  Refer to #HeapBufMP_ExtendedStats for more information
 415  *  regarding what information is returned.
 416  *
 417  *  In BIOS, HeapBufMP.trackAllocs needs to be set to 'true' in the
 418  *  configuration to get meaningful extended stats.
 419  *
 420  *  @param[in]  handle    Handle to previously created/opened instance.
 421  *  @param[out] stats     ExtendedStats structure
 422  *
 423  *  @sa     HeapBufMP_getStats
 424  */
 425 Void HeapBufMP_getExtendedStats(HeapBufMP_Handle handle,
 426                                 HeapBufMP_ExtendedStats *stats);
 427
 428 /*!
 429  *  @brief      Get memory statistics
 430  *
 431  *  @param[in]  handle    Handle to previously created/opened instance.
 432  *  @param[out] stats     Memory statistics structure
 433  *
 434  *  @sa     HeapBufMP_getExtendedStats
 435  */
 436 Void HeapBufMP_getStats(HeapBufMP_Handle handle, Ptr stats);
 437
 438 #if defined (__cplusplus)
 439 }
 440 #endif /* defined (__cplusplus) */
 441 #endif /* ti_ipc_HeapBufMP__include */