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