Debian Codegraph @

media_softlet/agnostic/common/codec/hal/codechal_common.h

raw
1 /*
2 * Copyright (c) 2021-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 codechal_common.h
24 //! \brief Defines the public interface for CodecHal.
25 //!
26 #ifndef __CODECHAL_COMMON_H__
27 #define __CODECHAL_COMMON_H__
28
29 #include "mos_os.h"
30 #include "mos_util_debug.h"
31 #include "codec_def_common.h"
32
33 class CodechalDebugInterface;
34 class CodechalHwInterfaceNext;
35 class CodechalSetting;
36
37 //------------------------------------------------------------------------------
38 // Simplified macros for debug message, Assert, Null check and MOS eStatus check
39 // within Codechal without the need to explicitly pass comp and sub-comp name
40 //------------------------------------------------------------------------------
41 //------------------------------------------------------------------------------
42 // Macros specific to MOS_CODEC_SUBCOMP_PUBLIC sub-comp
43 //------------------------------------------------------------------------------
44 #define CODECHAL_PUBLIC_ASSERT(_expr) \
45 MOS_ASSERT(MOS_COMPONENT_CODEC, MOS_CODEC_SUBCOMP_PUBLIC, _expr)
46
47 #define CODECHAL_PUBLIC_ASSERTMESSAGE(_message, ...) \
48 MOS_ASSERTMESSAGE(MOS_COMPONENT_CODEC, MOS_CODEC_SUBCOMP_PUBLIC, _message, ##__VA_ARGS__)
49
50 #define CODECHAL_PUBLIC_WARNINGMESSAGE(_message, ...) \
51 MOS_WARNINGMESSAGE(MOS_COMPONENT_CODEC, MOS_CODEC_SUBCOMP_PUBLIC, _message, ##__VA_ARGS__)
52
53 #define CODECHAL_PUBLIC_WARNINGMESSAGE(_message, ...) \
54 MOS_WARNINGMESSAGE(MOS_COMPONENT_CODEC, MOS_CODEC_SUBCOMP_PUBLIC, _message, ##__VA_ARGS__)
55
56 #define CODECHAL_PUBLIC_NORMALMESSAGE(_message, ...) \
57 MOS_NORMALMESSAGE(MOS_COMPONENT_CODEC, MOS_CODEC_SUBCOMP_PUBLIC, _message, ##__VA_ARGS__)
58
59 #define CODECHAL_PUBLIC_VERBOSEMESSAGE(_message, ...) \
60 MOS_VERBOSEMESSAGE(MOS_COMPONENT_CODEC, MOS_CODEC_SUBCOMP_PUBLIC, _message, ##__VA_ARGS__)
61
62 #define CODECHAL_PUBLIC_FUNCTION_ENTER \
63 MOS_FUNCTION_ENTER(MOS_COMPONENT_CODEC, MOS_CODEC_SUBCOMP_PUBLIC)
64
65 #define CODECHAL_PUBLIC_CHK_STATUS_RETURN(_stmt) \
66 MOS_CHK_STATUS_RETURN(MOS_COMPONENT_CODEC, MOS_CODEC_SUBCOMP_PUBLIC, _stmt)
67
68 #define CODECHAL_PUBLIC_CHK_STATUS_MESSAGE(_stmt, _message, ...) \
69 MOS_CHK_STATUS_MESSAGE(MOS_COMPONENT_CODEC, MOS_CODEC_SUBCOMP_PUBLIC, _stmt, _message, ##__VA_ARGS__)
70
71 #define CODECHAL_PUBLIC_CHK_NULL_RETURN(_ptr) \
72 MOS_CHK_NULL_RETURN(MOS_COMPONENT_CODEC, MOS_CODEC_SUBCOMP_PUBLIC, _ptr)
73
74 #define CODECHAL_PUBLIC_CHK_NULL_NO_STATUS_RETURN(_ptr) \
75 MOS_CHK_NULL_NO_STATUS_RETURN(MOS_COMPONENT_CODEC, MOS_CODEC_SUBCOMP_PUBLIC, _ptr)
76
77 #define CODECHAL_PUBLIC_CHK_STATUS_WITH_DESTROY_RETURN(_stmt, destroyFunction) \
78 { \
79 MOS_STATUS sts = (MOS_STATUS)(_stmt); \
80 MOS_CHK_COND_WITH_DESTROY_RETURN_VALUE(MOS_COMPONENT_CODEC, MOS_CODEC_SUBCOMP_ENCODE, (MOS_STATUS_SUCCESS != sts), destroyFunction, sts, "error status!") \
81 }
82
83 typedef struct CODECHAL_SSEU_SETTING
84 {
85 uint8_t ui8NumSlices;
86 uint8_t ui8NumSubSlices;
87 uint8_t ui8NumEUs;
88 uint8_t reserved; // Place holder for frequency setting
89 } CODECHAL_SSEU_SETTING, *PCODECHAL_SSEU_SETTING;
90
91 //!
92 //! \class CodechalResLock
93 //! \brief Help function to lock the resource, the resource will be unlock automatically when this class destroy.
94 //!
95 class CodechalResLock
96 {
97 public:
98 //! \brief lock flag
99 enum LockFlag
100 {
101 readOnly = 1, //!< lock with read only
102 writeOnly = 1 << 1, //!< lock with write only
103 tiledAsTiled = 1 << 2, //!< lock tile surface as tile format
104 noOverWrite = 1 << 3, //!< lock with no overwrite
105 noDecompress = 1 << 4, //!< lock with no decompress
106 uncached = 1 << 5, //!< lock with uncached
107 forceCached = 1 << 6 //!< lock with cache by force
108 };
109
110 //!
111 //! \brief Constructor
112 //!
113 CodechalResLock(PMOS_INTERFACE osInterface, PMOS_RESOURCE resource) : m_os(osInterface),
114 m_res(resource),
115 m_lockedPtr(nullptr)
116 {
117 }
118
119 //!
120 //! \brief Destructor
121 //!
122 ~CodechalResLock()
123 {
124 if (m_os != nullptr && m_res != nullptr && m_lockedPtr != nullptr)
125 {
126 m_os->pfnUnlockResource(m_os, m_res);
127 }
128 }
129
130 //!
131 //! \brief Lock the resource
132 //! \details Lock the resource, will be unlock automatically when this class destroy
133 //! \param [in] lockFlags
134 //! Combined lock flags, reference to enum LockFlag.
135 //!
136 //! \return void pointer
137 //! locked pointer if success, else return null pointer
138 //!
139 void *Lock(uint32_t lockFlags)
140 {
141 if (m_os == nullptr || m_res == nullptr)
142 {
143 return nullptr;
144 }
145
146 if (m_lockedPtr == nullptr)
147 {
148 MOS_LOCK_PARAMS mosLockFlags;
149 MOS_ZeroMemory(&mosLockFlags, sizeof(MOS_LOCK_PARAMS));
150
151 if ((lockFlags & readOnly) == readOnly)
152 {
153 mosLockFlags.ReadOnly = 1;
154 }
155
156 if ((lockFlags & writeOnly) == writeOnly)
157 {
158 mosLockFlags.WriteOnly = 1;
159 }
160
161 if ((lockFlags & tiledAsTiled) == tiledAsTiled)
162 {
163 mosLockFlags.TiledAsTiled = 1;
164 }
165
166 if ((lockFlags & noOverWrite) == noOverWrite)
167 {
168 mosLockFlags.NoOverWrite = 1;
169 }
170
171 if ((lockFlags & noDecompress) == noDecompress)
172 {
173 mosLockFlags.NoDecompress = 1;
174 }
175
176 if ((lockFlags & uncached) == uncached)
177 {
178 mosLockFlags.Uncached = 1;
179 }
180
181 if ((lockFlags & forceCached) == forceCached)
182 {
183 mosLockFlags.ForceCached = 1;
184 }
185
186 m_lockedPtr = m_os->pfnLockResource(
187 m_os,
188 m_res,
189 &mosLockFlags);
190 }
191
192 return m_lockedPtr;
193 }
194
195 private:
196 PMOS_INTERFACE m_os;
197 PMOS_RESOURCE m_res;
198 void *m_lockedPtr;
199
200 MEDIA_CLASS_DEFINE_END(CodechalResLock)
201 };
202
203 /*! \brief Settings used to create the CodecHal device.
204 */
205 typedef struct _CODECHAL_STANDARD_INFO
206 {
207 CODECHAL_FUNCTION CodecFunction; //!< High level codec functionality requested.
208 uint32_t Mode; //!< Mode requested (high level combination between Standard and CodecFunction).
209 /*! \brief Applies to decode only, hybrid decoding requested.
210 *
211 * Hybrid decoding uses EU kernels when FF HW is not available.
212 */
213 bool bIsHybridCodec;
214 } CODECHAL_STANDARD_INFO, *PCODECHAL_STANDARD_INFO;
215
216 //!
217 //! \class Codechal
218 //! \brief This class defines the common member fields, functions etc as Codechal base class.
219 //!
220 class Codechal
221 {
222 public:
223 //!
224 //! \brief Constructor
225 //! \param [in] hwInterface
226 //! Hardware interface
227 //! \param [in] debugInterface
228 //! Debug interface
229 //!
230 Codechal(
231 CodechalHwInterfaceNext *hwInterface,
232 CodechalDebugInterface *debugInterface);
233
234 //!
235 //! \brief Copy constructor
236 //!
237 Codechal(const Codechal&) = delete;
238
239 //!
240 //! \brief Copy assignment operator
241 //!
242 Codechal& operator=(const Codechal&) = delete;
243
244 //!
245 //! \brief Destructor
246 //!
247 virtual ~Codechal();
248
249 //!
250 //! \brief Allocate and intialize the Codechal.
251 //! \param [in] codecHalSettings
252 //! Settings used to finalize the creation of the CodecHal device
253 //! \return MOS_STATUS
254 //! MOS_STATUS_SUCCESS if success else fail reason
255 //!
256 virtual MOS_STATUS Allocate(CodechalSetting *codecHalSettings);
257
258 //!
259 //! \brief Signals the beginning of a picture.
260 //! \details Initializes necessary parameters to perform the requested operation.
261 //! \return MOS_STATUS
262 //! MOS_STATUS_SUCCESS if success else fail reason
263 //!
264 virtual MOS_STATUS BeginFrame();
265
266 //!
267 //! \brief Signals the end of a picture.
268 //! \details This function closes out the picture which was started by BeginFrame().
269 //! All Execute() calls for a particular picture must be complete before
270 //! EndFrame() is called. Resets all current picture parameters in
271 //! preparation for the next BeginFrame(). For decode, in the case
272 //! of incomplete frames, if the picture is still incomplete at EndFrame(),
273 //! CodecHal conceals the error internally and submits the codec workload.
274 //! \return MOS_STATUS
275 //! MOS_STATUS_SUCCESS if success else fail reason
276 //!
277 virtual MOS_STATUS EndFrame();
278
279 virtual MOS_STATUS Reformat();
280
281 //!
282 //! \brief Performs the operation requested by the codec function.
283 //! \param [in] params
284 //! Parameters need to perform the requested function. The parameter structure
285 //! changes based on codec function.
286 //! \return MOS_STATUS
287 //! MOS_STATUS_SUCCESS if success else fail reason
288 //!
289 virtual MOS_STATUS Execute(void *params);
290
291 //!
292 //! \brief Gets available statuses for executed pictures.
293 //! \details All pictures for which EndFrame() has been called are eligable
294 //! for status reporting. Once a successful or error status is reported out by
295 //! CodecHal, it is discarded.
296 //! \param [out] status
297 //! Array to store statuses up to a maximum of wNumStatus, valid pointer
298 //! must be passed in to GetStatusReport()
299 //! \param [in] numStatus
300 //! The size of the pCodecStatus array
301 //! \return MOS_STATUS
302 //! MOS_STATUS_SUCCESS if success else fail reason
303 //!
304 virtual MOS_STATUS GetStatusReport(
305 void *status,
306 uint16_t numStatus);
307
308 //!
309 //! \brief Get Encode Status for Vulkan Query Pool
310 //! \details Retrieve the necessary status and results for the Vulkan query pool
311 //! from the status buffer, such as bitstream size, hardware encoding status, bitstream offset
312 //! \param [in] queryFrameIndex
313 //! The specified frame index
314 //! [in] pData
315 //! Points to the buffer passed by Vulkan for storing the results.
316 //! [in] dataOffset
317 //! Starting position for writing to pData
318 //! [in] is64bit
319 //! Whether each result is 64-bit, otherwise 32-bit.
320 //! [in] reportStatus
321 //! Whether the encode status needs to be returned
322 //! [in] reportOffset
323 //! Whether the bitstream offset needs to be returned
324 //! [in] reportBitstream
325 //! Whether the bitstream size needs to be returned
326 //! \return MOS_STATUS
327 //! MOS_STATUS_SUCCESS if success, else fail reason
328 //!
329 virtual MOS_STATUS GetVulkanQueryPoolResults(
330 uint32_t queryFrameIndex,
331 void *pData,
332 uint64_t dataOffset,
333 bool is64bit,
334 uint8_t reportStatus,
335 bool reportOffset,
336 bool reportBitstream)
337 {
338 return MOS_STATUS_SUCCESS;
339 }
340
341
342 //!
343 //! \brief Destroy codechl state
344 //!
345 //! \return void
346 //!
347 virtual void Destroy();
348
349 //!
350 //! \brief Resolve MetaData.
351 //! \details Resolve MetaData from Input to Output.
352 //! \param [out] pOutput
353 //! Resolved Metadata resource.
354 //! \param [in] pInput
355 //! Metadata resource to be resolve.
356 //! \return MOS_STATUS
357 //! MOS_STATUS_SUCCESS if success else fail reason
358 //!
359 virtual MOS_STATUS ResolveMetaData(PMOS_RESOURCE pInput, PMOS_RESOURCE pOutput);
360
361 //!
362 //! \brief Report Error Flag.
363 //! \details Report error flag to metadata buffer
364 //! \param [in] pMetadataBuffer
365 //! Metadata buffer.
366 //! \param [in] size
367 //! Metadata size.
368 //! \param [in] offset
369 //! Error flag offset in the metdata.
370 //! \param [in] flag
371 //! Flag to report.
372 //! \return MOS_STATUS
373 //! MOS_STATUS_SUCCESS if success else fail reason
374 //!
375 virtual MOS_STATUS ReportErrorFlag(PMOS_RESOURCE pMetadataBuffer, uint32_t size,
376 uint32_t offset, uint32_t flag);
377
378 //!
379 //! \brief Gets hardware interface.
380 //! \return CodechalHwInterface
381 //! return hardware interface
382 //!
383 CodechalHwInterfaceNext *GetHwInterface() { return m_hwInterface; }
384
385 //!
386 //! \brief Gets OS interface.
387 //! \return PMOS_INTERFACE
388 //! return OS interface
389 //!
390 PMOS_INTERFACE GetOsInterface() { return m_osInterface; }
391
392 //!
393 //! \brief Gets debug interface.
394 //! \return CodechalDebugInterface
395 //! return debug interface
396 //!
397 CodechalDebugInterface *GetDebugInterface() { return m_debugInterface; }
398
399 //!
400 //! \brief Check if Apogeios enabled.
401 //! \return bool
402 //! return m_apogeiosEnable
403 //!
404 bool IsApogeiosEnabled() { return m_apogeiosEnable; }
405 protected:
406 //! \brief HW Inteface
407 //! \details Responsible for constructing all defined states and commands.
408 //! Each HAL has a separate OS interface.
409 CodechalHwInterfaceNext *m_hwInterface = nullptr;
410
411 //! \brief Os Inteface
412 //! \details Used to abstract all OS and KMD interactions such that CodecHal may be
413 //! OS agnostic. Each HAL has a separate OS interface.
414 PMOS_INTERFACE m_osInterface = nullptr;
415
416 //! \brief Interface used for debug dumps.
417 //! \details This interface is only valid for release internal and debug builds.
418 CodechalDebugInterface *m_debugInterface = nullptr;
419
420 //! \brief Interface used for debug dumps in GetStatusReport.
421 //! \details This interface is only valid for release internal and debug builds.
422 CodechalDebugInterface *m_statusReportDebugInterface = nullptr;
423
424 //! \brief Indicates whether or not using null hardware
425 bool m_useNullHw[MOS_GPU_CONTEXT_MAX] = { false };
426
427 //! \brief Apogeios Enable Flag
428 bool m_apogeiosEnable = false;
429
430 //!< usersettingInstance
431 MediaUserSettingSharedPtr m_userSettingPtr = nullptr;
432 MEDIA_CLASS_DEFINE_END(Codechal)
433 };
434
435 #endif