Debian Codegraph @

media_common/agnostic/common/heap_manager/heap.h

raw
1 /*
2 * Copyright (c) 2017-2025, 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 warning message level
47 #define HEAP_WARNINGMESSAGE(_message, ...) \
48 MOS_WARNINGMESSAGE(MOS_COMPONENT_HW, MOS_SUBCOMP_SELF, _message, ##__VA_ARGS__)
49 //! Prints \a _message at normal message level
50 #define HEAP_NORMALMESSAGE(_message, ...) \
51 MOS_NORMALMESSAGE(MOS_COMPONENT_HW, MOS_SUBCOMP_SELF, _message, ##__VA_ARGS__)
52 //! Prints \a _message at verbose message level
53 #define HEAP_VERBOSEMESSAGE(_message, ...) \
54 MOS_VERBOSEMESSAGE(MOS_COMPONENT_HW, MOS_SUBCOMP_SELF, _message, ##__VA_ARGS__)
55 //! Prints the function name at function enter message level
56 #define HEAP_FUNCTION_ENTER \
57 MOS_FUNCTION_ENTER(MOS_COMPONENT_HW, MOS_SUBCOMP_SELF)
58 //! Prints the function name at verbose function enter message level
59 #define HEAP_FUNCTION_ENTER_VERBOSE \
60 MOS_FUNCTION_ENTER_VERBOSE(MOS_COMPONENT_HW, MOS_SUBCOMP_SELF)
61
62 //! \brief Generic heap for storing client written data in graphics memory
63 class Heap
64 {
65 friend class MemoryBlockInternal;
66 friend class MemoryBlockManager;
67
68 public:
69 //!
70 //! \brief Default constructor
71 //! Identifier for the heap
72 //!
73 Heap();
74
75 //!
76 //! \brief Copy constructor
77 //!
78 Heap(const Heap&) = delete;
79
80 //!
81 //! \brief Copy assignment operator
82 //!
83 Heap& operator=(const Heap&) = delete;
84
85 //!
86 //! \brief Constructor
87 //! \param [in] id
88 //! Identifier for the heap
89 //!
90 Heap(uint32_t id);
91 virtual ~Heap();
92
93 //!
94 //! \brief Dumps the contents of the heap
95 //! \return MOS_STATUS
96 //! MOS_STATUS_SUCCESS if success, else fail reason
97 //!
98 MOS_STATUS Dump();
99
100 //!
101 //! \brief Checks heap for validity
102 //! \return bool
103 //! true if the heap is valid and false if not
104 //!
105 bool IsValid() { return (m_size > 0); }
106
107 //!
108 //! \brief Gets the graphics resource for the heap
109 //! \param [out] resource
110 //! Container for the output graphics resource
111 //! \return MOS_RESOURCE*
112 //! Valid pointer if success, nullptr for any fail
113 //!
114 MOS_RESOURCE* GetResource()
115 {
116 HEAP_FUNCTION_ENTER_VERBOSE;
117 if (m_size && !Mos_ResourceIsNull(m_resource))
118 {
119 return m_resource;
120 }
121 HEAP_ASSERTMESSAGE("Resource is not valid");
122 return nullptr;
123 }
124
125 //!
126 //! \brief Gets the size of the heap
127 //! \return The size of the heap \see m_size
128 //!
129 uint32_t GetSize() { return m_size; }
130
131 //!
132 //! \brief Gets the used size of the heap
133 //! \return The amount of space used in the heaps \see m_usedSize
134 //!
135 uint32_t GetUsedSize() { return m_usedSpace; }
136
137 //!
138 //! \brief Gets the ID for the heap
139 //! \return The Heap ID \see m_id
140 //!
141 uint32_t GetId() { return m_id; }
142
143 //!
144 //! \brief Whether or not the heap has been marked for freeing.
145 //! \return If the heap is being freed \see m_freeInProgress
146 //!
147 bool IsFreeInProgress() { return m_freeInProgress; }
148
149 //! \brief Invalid heap ID.
150 static const uint8_t m_invalidId = 0;
151
152 //!
153 //! \brief Mark the heap as hardware write only heap or not
154 void SetHeapHwWriteOnly(bool isHwWriteOnly) { m_hwWriteOnly = isHwWriteOnly; }
155
156 protected:
157 //!
158 //! \brief Stores the provided OS interface in the heap
159 //! \param [in] osInterface
160 //! Must be valid
161 //! \return MOS_STATUS
162 //! MOS_STATUS_SUCCESS if success, else fail reason
163 //!
164 MOS_STATUS RegisterOsInterface(PMOS_INTERFACE osInterface);
165
166 //!
167 //! \brief Allocates a graphics resource of size \a heapSize
168 //! \param [in] heapSize
169 //! The size of the state heap, must be non-zero
170 //! \param [in] keepLocked
171 //! Locks the heap when allocated and does not unlock it until it is destroyed
172 //! \return MOS_STATUS
173 //! MOS_STATUS_SUCCESS if success, else fail reason
174 //!
175 MOS_STATUS Allocate(uint32_t heapSize, bool keepLocked);
176
177 //!
178 //! \brief Locks the heap asynchonously
179 //! \return uint8_t*
180 //! If successful, pointer to data in the heap resource; if failed, nullptr \see m_resource
181 //!
182 uint8_t* Lock();
183
184 //!
185 //! \brief Unlocks the heap
186 //!
187 void Unlock()
188 {
189 HEAP_FUNCTION_ENTER_VERBOSE;
190 if (!m_keepLocked)
191 {
192 if (m_osInterface == nullptr)
193 {
194 HEAP_ASSERTMESSAGE("Invalid m_osInterface(nullptr)");
195 return;
196 }
197
198 m_osInterface->pfnUnlockResource(m_osInterface, m_resource);
199 }
200 }
201
202 //!
203 //! \brief Prepares the heap for being freed which will occur when all blocks are
204 //! no longer in use.
205 //!
206 void PrepareForFree()
207 {
208 HEAP_FUNCTION_ENTER;
209 m_freeInProgress = true;
210 }
211
212 //!
213 //! \brief Adjusts the free space in the heap.
214 //! \param [in] addedSpace
215 //! Space to be added and subtracted from the free and used space
216 //! \return MOS_STATUS
217 //! MOS_STATUS_SUCCESS if success, else fail reason
218 //!
219 MOS_STATUS AdjustFreeSpace(uint32_t addedSpace);
220
221 //!
222 //! \brief Adjusts the used space in the heap.
223 //! \param [in] addedSpace
224 //! Space to be added and subtracted from the free and used space
225 //! \return MOS_STATUS
226 //! MOS_STATUS_SUCCESS if success, else fail reason
227 //!
228 MOS_STATUS AdjustUsedSpace(uint32_t addedSpace);
229
230 private:
231 //! \brief Indicates that the heap is in the process of being freed
232 bool m_freeInProgress = false;
233 bool m_keepLocked = false; //!< Indictaes that heap is kept locked until freed.
234 PMOS_RESOURCE m_resource = nullptr; //!< Graphics resource for the heap.
235 uint32_t m_size = 0; //!< The size of the heap.
236 //! \brief Pointer to the locked heap data.
237 //! \details This pointer is only valid if the heap is locked always
238 uint8_t *m_lockedHeap = nullptr;
239 uint32_t m_freeSpace = 0; //!< The amount of space available in the heap
240 uint32_t m_usedSpace = 0; //!< The amount of used space within the heap
241 //! \brief OS interface used for managing graphics resources
242 PMOS_INTERFACE m_osInterface = nullptr;
243 //! \brief unique identifier for the heap within the heap manager
244 uint32_t m_id = m_invalidId;
245 bool m_hwWriteOnly = false; //!< Indictaes that heap is used by hardware write only.
246 };
247 #endif // __HEAP_H__