heap.h 5.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159
  1. /*!
  2. *****************************************************************************
  3. *
  4. * @File heap.h
  5. * @Description MMU Library: device virtual allocation (heap)
  6. * ---------------------------------------------------------------------------
  7. *
  8. * Copyright (c) Imagination Technologies Ltd.
  9. *
  10. * The contents of this file are subject to the MIT license as set out below.
  11. *
  12. * Permission is hereby granted, free of charge, to any person obtaining a
  13. * copy of this software and associated documentation files (the "Software"),
  14. * to deal in the Software without restriction, including without limitation
  15. * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  16. * and/or sell copies of the Software, and to permit persons to whom the
  17. * Software is furnished to do so, subject to the following conditions:
  18. *
  19. * The above copyright notice and this permission notice shall be included in
  20. * all copies or substantial portions of the Software.
  21. *
  22. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  23. * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  24. * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  25. * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  26. * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  27. * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  28. * THE SOFTWARE.
  29. *
  30. * Alternatively, the contents of this file may be used under the terms of the
  31. * GNU General Public License Version 2 ("GPL")in which case the provisions of
  32. * GPL are applicable instead of those above.
  33. *
  34. * If you wish to allow use of your version of this file only under the terms
  35. * of GPL, and not to allow others to use your version of this file under the
  36. * terms of the MIT license, indicate your decision by deleting the provisions
  37. * above and replace them with the notice and other provisions required by GPL
  38. * as set out in the file called "GPLHEADER" included in this distribution. If
  39. * you do not delete the provisions above, a recipient may use your version of
  40. * this file under the terms of either the MIT license or GPL.
  41. *
  42. * This License is also included in this distribution in the file called
  43. * "MIT_COPYING".
  44. *
  45. *****************************************************************************/
  46. #ifndef IMGMMU_HEAP_H
  47. #define IMGMMU_HEAP_H
  48. /**
  49. * @defgroup IMGMMU_heap MMU Heap Interface
  50. * @brief The API for the device virtual address Heap - must be implemented
  51. * (see tal_heap.c for an example implementation)
  52. * @ingroup IMGMMU_lib
  53. * @{
  54. */
  55. /*-----------------------------------------------------------------------------
  56. * Following elements are in the IMGMMU_heap documentation module
  57. *---------------------------------------------------------------------------*/
  58. /** @brief An allocation on a heap. */
  59. struct imgmmu_halloc {
  60. /** @brief Start of the allocation */
  61. uint64_t vaddr;
  62. /** @brief Size in bytes */
  63. size_t size;
  64. };
  65. /**
  66. * @brief A virtual address heap - not directly related to HW MMU directory
  67. * entry
  68. */
  69. struct imgmmu_heap {
  70. /** @brief Start of device virtual address */
  71. uint64_t vaddr_start;
  72. /** @brief Allocation atom in bytes */
  73. size_t atom;
  74. /** @brief Total size of the heap in bytes */
  75. size_t size;
  76. /** Guard band indicator. */
  77. bool guard_band;
  78. };
  79. /**
  80. * @name Device virtual address allocation (heap management)
  81. * @{
  82. */
  83. /**
  84. * @brief Create a Heap
  85. *
  86. * @param vaddr_start start of the heap - must be a multiple of atom
  87. * @param atom the minimum possible allocation on the heap in bytes
  88. * - usually related to the system page size
  89. * @param size total size of the heap in bytes
  90. * @param guard_band enables/disables creation of a gap
  91. * between virtual addresses.
  92. * NOTE: The gap has size of atom.
  93. * @param res must be non-NULL - used to give detail about error
  94. *
  95. * @return pointer to the new Heap object and res is 0
  96. * @return NULL and the value of res can be:
  97. * @li -ENOMEM if internal allocation failed
  98. */
  99. struct imgmmu_heap *imgmmu_hcreate(uintptr_t vaddr_start,
  100. size_t atom, size_t size, bool guard_band, int *res);
  101. /**
  102. * @brief Allocate from a heap
  103. *
  104. * @warning Heap do not relate to each other, therefore one must insure that
  105. * they should not overlap if they should not.
  106. *
  107. * @param heap must not be NULL
  108. * @param size allocation size in bytes
  109. * @param res must be non-NULL - used to give details about error
  110. *
  111. * @return pointer to the new halloc object and res is 0
  112. * @return NULL and the value of res can be:
  113. * @li -EINVAL if the give size is not a multiple of
  114. * heap->atom
  115. * @li -ENOMEM if the internal structure allocation failed
  116. * @li -EFAULT if the internal device memory allocator did not
  117. * find a suitable virtual address
  118. */
  119. struct imgmmu_halloc *imgmmu_hallocate(struct imgmmu_heap *heap, size_t size,
  120. int *res);
  121. /**
  122. * @brief Liberate an allocation
  123. *
  124. * @return 0
  125. */
  126. int imgmmu_hfree(struct imgmmu_halloc *alloc);
  127. /**
  128. * @brief Destroy a heap object
  129. *
  130. * @return 0
  131. * @return -EFAULT if the given heap still has attached
  132. * allocation
  133. */
  134. int imgmmu_hdestroy(struct imgmmu_heap *heap);
  135. /**
  136. * @}
  137. */
  138. /*-----------------------------------------------------------------------------
  139. * End of the public functions
  140. *---------------------------------------------------------------------------*/
  141. /**
  142. * @}
  143. */
  144. /*-----------------------------------------------------------------------------
  145. * End of the IMGMMU_heap documentation module
  146. *---------------------------------------------------------------------------*/
  147. #endif /* IMGMMU_HEAP_H */