1 /* 2 * Copyright (c) 2017, Intel Corporation 3 * 4 * Permission is hereby granted, free of charge, to any person obtaining a 5 * copy of this software and associated documentation files (the "Software"), 6 * to deal in the Software without restriction, including without limitation 7 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 8 * and/or sell copies of the Software, and to permit persons to whom the 9 * Software is furnished to do so, subject to the following conditions: 10 * 11 * The above copyright notice and this permission notice shall be included 12 * in all copies or substantial portions of the Software. 13 * 14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 15 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 17 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR 18 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 19 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 20 * OTHER DEALINGS IN THE SOFTWARE. 21 */ 22 //! 23 //! \file heap.h 24 //! \brief A heap is a buffer in graphics memory in which the driver may store information 25 //! \details Heaps are created for the client via the heap manager, through which the client 26 //! is expected to claim blocks of memory for data storage. The client has no direct 27 //! access to the heap. 28 //! 29 30 #ifndef __HEAP_H__ 31 #define __HEAP_H__ 32 33 #include "mos_os.h" 34 #include "mos_util_debug.h" 35 #include "mos_interface.h" 36 37 //! Evaluates the status and returns if failure 38 #define HEAP_CHK_STATUS(_stmt) \ 39 MOS_CHK_STATUS_RETURN(MOS_COMPONENT_HW, MOS_HW_SUBCOMP_ALL, _stmt) 40 //! Checks the pointer and returns if nullptr 41 #define HEAP_CHK_NULL(_ptr) \ 42 MOS_CHK_NULL_RETURN(MOS_COMPONENT_HW, MOS_HW_SUBCOMP_ALL, _ptr) 43 //! Asserts and prints \a _message at critical message level 44 #define HEAP_ASSERTMESSAGE(_message, ...) \ 45 MOS_ASSERTMESSAGE(MOS_COMPONENT_HW, MOS_SUBCOMP_SELF, _message, ##__VA_ARGS__) 46 //! Prints \a _message at normal message level 47 #define HEAP_NORMALMESSAGE(_message, ...) \ 48 MOS_NORMALMESSAGE(MOS_COMPONENT_HW, MOS_SUBCOMP_SELF, _message, ##__VA_ARGS__) 49 //! Prints \a _message at verbose message level 50 #define HEAP_VERBOSEMESSAGE(_message, ...) \ 51 MOS_VERBOSEMESSAGE(MOS_COMPONENT_HW, MOS_SUBCOMP_SELF, _message, ##__VA_ARGS__) 52 //! Prints the function name at function enter message level 53 #define HEAP_FUNCTION_ENTER \ 54 MOS_FUNCTION_ENTER(MOS_COMPONENT_HW, MOS_SUBCOMP_SELF) 55 //! Prints the function name at verbose function enter message level 56 #define HEAP_FUNCTION_ENTER_VERBOSE \ 57 MOS_FUNCTION_ENTER_VERBOSE(MOS_COMPONENT_HW, MOS_SUBCOMP_SELF) 58 59 //! \brief Generic heap for storing client written data in graphics memory 60 class Heap 61 { 62 friend class MemoryBlockInternal; 63 friend class MemoryBlockManager; 64 65 public: 66 //! 67 //! \brief Default constructor 68 //! Identifier for the heap 69 //! 70 Heap(); 71 72 //! 73 //! \brief Copy constructor 74 //! 75 Heap(const Heap&) = delete; 76 77 //! 78 //! \brief Copy assignment operator 79 //! 80 Heap& operator=(const Heap&) = delete; 81 82 //! 83 //! \brief Constructor 84 //! \param [in] id 85 //! Identifier for the heap 86 //! 87 Heap(uint32_t id); 88 virtual ~Heap(); 89 90 //! 91 //! \brief Dumps the contents of the heap 92 //! \return MOS_STATUS 93 //! MOS_STATUS_SUCCESS if success, else fail reason 94 //! 95 MOS_STATUS Dump(); 96 97 //! 98 //! \brief Checks heap for validity 99 //! \return bool 100 //! true if the heap is valid and false if not 101 //! IsValid()102 bool IsValid() { return (m_size > 0); } 103 104 //! 105 //! \brief Gets the graphics resource for the heap 106 //! \param [out] resource 107 //! Container for the output graphics resource 108 //! \return MOS_RESOURCE* 109 //! Valid pointer if success, nullptr for any fail 110 //! GetResource()111 MOS_RESOURCE* GetResource() 112 { 113 HEAP_FUNCTION_ENTER_VERBOSE; 114 if (m_size && !Mos_ResourceIsNull(m_resource)) 115 { 116 return m_resource; 117 } 118 HEAP_ASSERTMESSAGE("Resource is not valid"); 119 return nullptr; 120 } 121 122 //! 123 //! \brief Gets the size of the heap 124 //! \return The size of the heap \see m_size 125 //! GetSize()126 uint32_t GetSize() { return m_size; } 127 128 //! 129 //! \brief Gets the used size of the heap 130 //! \return The amount of space used in the heaps \see m_usedSize 131 //! GetUsedSize()132 uint32_t GetUsedSize() { return m_usedSpace; } 133 134 //! 135 //! \brief Gets the ID for the heap 136 //! \return The Heap ID \see m_id 137 //! GetId()138 uint32_t GetId() { return m_id; } 139 140 //! 141 //! \brief Whether or not the heap has been marked for freeing. 142 //! \return If the heap is being freed \see m_freeInProgress 143 //! IsFreeInProgress()144 bool IsFreeInProgress() { return m_freeInProgress; } 145 146 //! \brief Invalid heap ID. 147 static const uint8_t m_invalidId = 0; 148 149 //! 150 //! \brief Mark the heap as hardware write only heap or not SetHeapHwWriteOnly(bool isHwWriteOnly)151 void SetHeapHwWriteOnly(bool isHwWriteOnly) { m_hwWriteOnly = isHwWriteOnly; } 152 153 protected: 154 //! 155 //! \brief Stores the provided OS interface in the heap 156 //! \param [in] osInterface 157 //! Must be valid 158 //! \return MOS_STATUS 159 //! MOS_STATUS_SUCCESS if success, else fail reason 160 //! 161 MOS_STATUS RegisterOsInterface(PMOS_INTERFACE osInterface); 162 163 //! 164 //! \brief Allocates a graphics resource of size \a heapSize 165 //! \param [in] heapSize 166 //! The size of the state heap, must be non-zero 167 //! \param [in] keepLocked 168 //! Locks the heap when allocated and does not unlock it until it is destroyed 169 //! \return MOS_STATUS 170 //! MOS_STATUS_SUCCESS if success, else fail reason 171 //! 172 MOS_STATUS Allocate(uint32_t heapSize, bool keepLocked); 173 174 //! 175 //! \brief Locks the heap asynchonously 176 //! \return uint8_t* 177 //! If successful, pointer to data in the heap resource; if failed, nullptr \see m_resource 178 //! 179 uint8_t* Lock(); 180 181 //! 182 //! \brief Unlocks the heap 183 //! Unlock()184 void Unlock() 185 { 186 HEAP_FUNCTION_ENTER_VERBOSE; 187 if (!m_keepLocked) 188 { 189 if (m_osInterface == nullptr) 190 { 191 HEAP_ASSERTMESSAGE("Invalid m_osInterface(nullptr)"); 192 return; 193 } 194 195 m_osInterface->pfnUnlockResource(m_osInterface, m_resource); 196 } 197 } 198 199 //! 200 //! \brief Prepares the heap for being freed which will occur when all blocks are 201 //! no longer in use. 202 //! PrepareForFree()203 void PrepareForFree() 204 { 205 HEAP_FUNCTION_ENTER; 206 m_freeInProgress = true; 207 } 208 209 //! 210 //! \brief Adjusts the free space in the heap. 211 //! \param [in] addedSpace 212 //! Space to be added and subtracted from the free and used space 213 //! \return MOS_STATUS 214 //! MOS_STATUS_SUCCESS if success, else fail reason 215 //! 216 MOS_STATUS AdjustFreeSpace(uint32_t addedSpace); 217 218 //! 219 //! \brief Adjusts the used space in the heap. 220 //! \param [in] addedSpace 221 //! Space to be added and subtracted from the free and used space 222 //! \return MOS_STATUS 223 //! MOS_STATUS_SUCCESS if success, else fail reason 224 //! 225 MOS_STATUS AdjustUsedSpace(uint32_t addedSpace); 226 227 private: 228 //! \brief Indicates that the heap is in the process of being freed 229 bool m_freeInProgress = false; 230 bool m_keepLocked = false; //!< Indictaes that heap is kept locked until freed. 231 PMOS_RESOURCE m_resource = nullptr; //!< Graphics resource for the heap. 232 uint32_t m_size = 0; //!< The size of the heap. 233 //! \brief Pointer to the locked heap data. 234 //! \details This pointer is only valid if the heap is locked always 235 uint8_t *m_lockedHeap = nullptr; 236 uint32_t m_freeSpace = 0; //!< The amount of space available in the heap 237 uint32_t m_usedSpace = 0; //!< The amount of used space within the heap 238 //! \brief OS interface used for managing graphics resources 239 PMOS_INTERFACE m_osInterface = nullptr; 240 //! \brief unique identifier for the heap within the heap manager 241 uint32_t m_id = m_invalidId; 242 bool m_hwWriteOnly = false; //!< Indictaes that heap is used by hardware write only. 243 }; 244 #endif // __HEAP_H__ 245