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_ 191