Debian Codegraph @

media_driver/agnostic/common/cm/cm_event.h

raw
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 cm_event.h
24 //! \brief Contains CmEvent declarations.
25 //!
26
27 #ifndef MEDIADRIVER_AGNOSTIC_COMMON_CM_CMEVENT_H_
28 #define MEDIADRIVER_AGNOSTIC_COMMON_CM_CMEVENT_H_
29
30 #include "cm_def.h"
31
32 enum CM_STATUS
33 {
34 CM_STATUS_QUEUED = 0,
35 CM_STATUS_FLUSHED = 1,
36 CM_STATUS_FINISHED = 2,
37 CM_STATUS_STARTED = 3,
38 CM_STATUS_RESET = 4
39 };
40
41 enum CM_EVENT_PROFILING_INFO
42 {
43 CM_EVENT_PROFILING_HWSTART,
44 CM_EVENT_PROFILING_HWEND,
45 CM_EVENT_PROFILING_SUBMIT,
46 CM_EVENT_PROFILING_COMPLETE,
47 CM_EVENT_PROFILING_ENQUEUE,
48 CM_EVENT_PROFILING_KERNELCOUNT,
49 CM_EVENT_PROFILING_KERNELNAMES,
50 CM_EVENT_PROFILING_THREADSPACE,
51 CM_EVENT_PROFILING_CALLBACK
52 };
53
54 namespace CMRT_UMD
55 {
56 //! \brief A CmEvent object is genereated after a task is enqueued.
57 //! \details A CmEvent object is generated after a task(one kernel or multiples
58 //! kernels running concurrently) is enqueued for execution.This
59 //! event object can subsequently be queried to determine the status
60 //! of execution and other execution related information.
61 class CmEvent
62 {
63 public:
64 //!
65 //! \brief Query the status of the task associated with the event.
66 //! \details An event is generated when a task (one kernel or multiples
67 //! kernels running concurrently) is enqueued. This is a
68 //! non-blocking call.
69 //! \param [out] status
70 //! The reference to the execution status. Four status values,
71 //! CM_STATUS_QUEUED, CM_STATUS_FLUSHED, CM_STATUS_STARTED, and
72 //! CM_STATUS_FINISHED are supported. CM_STATUS_FLUSHED means
73 //! that the task is already sent to driver/hardware.
74 //! CM_STATUS_STARTED means hardware starts to execute the task.
75 //! CM_STATUS_FINISHED means hardware has finished the
76 //! execution of all kernels in the task. In Emulation/Simulation
77 //! mode since the Enqueue operation is a blocking call, this
78 //! function always returns CM_STATUS_FINISHED.
79 //! \retval CM_SUCCESS if the status is successfully returned.
80 //! \retval CM_FAILURE if otherwise.
81 //!
82 CM_RT_API virtual int32_t GetStatus(CM_STATUS &status) = 0 ;
83
84 //!
85 //! \brief Query the execution time of a task (one kernel or multiples
86 //! kernels running concurrently) in the unit of nanoseconds.
87 //! \details The execution time is measured from the time the task
88 //! started execution in GPU to the time when the task finished
89 //! execution.We recommend pair this API with
90 //! CmEvent::WaitForTaskFinished in practice when you try to
91 //! get GPU HW execution time. This is a non-blocking call.
92 //! In Emulation/Simulation mode this function always returns 100.
93 //! \param [out] time
94 //! Reference to time.
95 //! \retval CM_SUCCESS if the execution time is successfully returned.
96 //! \retval CM_FAILURE if not, e.g. the task hasn't finished.
97 //!
98 CM_RT_API virtual int32_t GetExecutionTime(uint64_t &time) = 0;
99
100 //!
101 //! \brief Wait for the task associated with the event finishing
102 //! execution on GPU (task status became CM_STATUS_FINISHED).
103 //! \details It applies event driven synchronization between GPU and CPU
104 //! to reduce CPU usage and power consumption in the waiting:
105 //! current process goes to sleep and waits for the
106 //! notification from OS until task finishes. We recommend use
107 //! this API followed by CmEvent::GetExecutionTime when you try
108 //! to get GPU HW execution time.
109 //! \param [out] timeOutMs
110 //! Timeout in milliseconds for the waiting, 2000 milliseconds
111 //! by-default.
112 //! \retval CM_SUCCESS if successfully wait and get notification from
113 //! OS.
114 //! \retval CM_NOT_IMPLEMENTED if DDI version is less than 2.4.
115 //! \retval CM_EVENT_DRIVEN_FAILURE otherwise.
116 //! \note This API is unnecessary to be added before the ReadSurface
117 //! method of class Surface2D/3D etc. We already apply
118 //! event-driven synchronization optimization inside
119 //! ReadSurface if the dependent event is given.
120 //!
121 CM_RT_API virtual int32_t
122 WaitForTaskFinished(uint32_t timeOutMs = CM_MAX_TIMEOUT_MS) = 0;
123
124 //!
125 //! \brief Gets surface details for GT-Pin.
126 //! \param [in] kernIndex
127 //! Index of the kernel which owns the surface.
128 //! \param [in] surfBTI
129 //! Index in Binding table for queried surface.
130 //! \param [out] outDetails
131 //! Detail info about this surface, which includes width,
132 //! height, depth, format, pitch, slice Pitch, surface base
133 //! address, tiled type, vertical offset, and horizontal offset.
134 //! \retval CM_SUCCESS if query is successfully finished.
135 //! \retval CM_NOT_IMPLEMENTED if DDI version is less than 2.3.
136 //! \retval CM_INVALID_ARG_VALUE if input parameter is invalid.
137 //! \retval CM_FAILURE otherwise.
138 //!
139 CM_RT_API virtual int32_t
140 GetSurfaceDetails(uint32_t kernIndex,
141 uint32_t surfBTI,
142 CM_SURFACE_DETAILS& outDetails) = 0;
143
144 //!
145 //! \brief This function can be used to get more profiling
146 //! information for vTune.
147 //! \details It can provided 9 profiling values, for profiling
148 //! information,including
149 //! CM_EVENT_PROFILING_HWSTART,CM_EVENT_PROFILING_HWEND,
150 //! CM_EVENT_PROFILING_SUBMIT,CM_EVENT_PROFILING_COMPLETE,
151 //! CM_EVENT_PROFILING_ENQUEUE,CM_EVENT_PROFILING_KERNELCOUNT,
152 //! CM_EVENT_PROFILING_KERNELNAMES,
153 //! CM_EVENT_PROFILING_THREADSPACE,
154 //! CM_EVENT_PROFILING_CALLBACK.
155 //! \param [in] infoType
156 //! One value of CM_EVENT_PROFILING_INFO, specify which
157 //! information to get.
158 //! \param [in] paramSize
159 //! Size of the parameter.
160 //! \param [in] inputValue
161 //! Pointer pointing to memory where to get kernel index or
162 //! callback function.
163 //! \param [out] value
164 //! Pointer pointing to memory where the cap information should
165 //! be returned.
166 //! \retval CM_SUCCESS if get information successfully.
167 //! \retval CM_FAILURE otherwise.
168 //!
169 CM_RT_API virtual int32_t GetProfilingInfo(CM_EVENT_PROFILING_INFO infoType,
170 size_t paramSize,
171 void *inputValue,
172 void *value) = 0;
173
174 //!
175 //! \brief Query the raw tick time of a task(one kernel or multiples
176 //! kernels running concurrently).
177 //! \details We recommend pair this API with
178 //! CmEvent::WaitForTaskFinished in practice when you try to
179 //! get HW execution tick time.
180 //! \param [out] ticks
181 //! Reference to time.
182 //! \retval CM_SUCCESS if the raw tick time is successfully returned.
183 //! \retval CM_FAILURE if not, e.g. the task hasn't finished.
184 //!
185 CM_RT_API virtual int32_t GetExecutionTickTime(uint64_t &ticks) = 0;
186
187 };
188 }; //namespace
189
190 #endif // #ifndef MEDIADRIVER_AGNOSTIC_COMMON_CM_CMEVENT_H_