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