| /*************************************************************************/ /*! |
| @File |
| @Title PVR synchronisation interface |
| @Copyright Copyright (c) Imagination Technologies Ltd. All Rights Reserved |
| @Description API for synchronisation functions for client side code |
| @License Dual MIT/GPLv2 |
| |
| The contents of this file are subject to the MIT license as set out below. |
| |
| Permission is hereby granted, free of charge, to any person obtaining a copy |
| of this software and associated documentation files (the "Software"), to deal |
| in the Software without restriction, including without limitation the rights |
| to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
| copies of the Software, and to permit persons to whom the Software is |
| furnished to do so, subject to the following conditions: |
| |
| The above copyright notice and this permission notice shall be included in |
| all copies or substantial portions of the Software. |
| |
| Alternatively, the contents of this file may be used under the terms of |
| the GNU General Public License Version 2 ("GPL") in which case the provisions |
| of GPL are applicable instead of those above. |
| |
| If you wish to allow use of your version of this file only under the terms of |
| GPL, and not to allow others to use your version of this file under the terms |
| of the MIT license, indicate your decision by deleting the provisions above |
| and replace them with the notice and other provisions required by GPL as set |
| out in the file called "GPL-COPYING" included in this distribution. If you do |
| not delete the provisions above, a recipient may use your version of this file |
| under the terms of either the MIT license or GPL. |
| |
| This License is also included in this distribution in the file called |
| "MIT-COPYING". |
| |
| EXCEPT AS OTHERWISE STATED IN A NEGOTIATED AGREEMENT: (A) THE SOFTWARE IS |
| PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING |
| BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR |
| PURPOSE AND NONINFRINGEMENT; AND (B) IN NO EVENT SHALL THE AUTHORS OR |
| COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER |
| IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN |
| CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| */ /**************************************************************************/ |
| #include "img_types.h" |
| #include "pvrsrv_error.h" |
| #include "pvr_debug.h" |
| #include "pvrsrv_sync_km.h" |
| |
| #ifndef PVRSRV_SYNC_UM_H |
| #define PVRSRV_SYNC_UM_H |
| #if defined (__cplusplus) |
| extern "C" { |
| #endif |
| |
| |
| /*************************************************************************/ /*! |
| @Function PVRSRVSyncInit |
| |
| @Description Initialise the synchronisation code for the calling |
| process. This has to be called before any other functions in |
| this synchronisation module. |
| |
| @Return PVRSRV_OK if the initialisation was successful |
| PVRSRV_ERROR_xxx if an error occurred |
| */ |
| /*****************************************************************************/ |
| IMG_EXPORT PVRSRV_ERROR |
| PVRSRVSyncInitI(void); |
| #define PVRSRVSyncInit(void) \ |
| PVRSRVSyncInitI(void) |
| |
| /*************************************************************************/ /*! |
| @Function PVRSRVSyncDeinit |
| |
| @Description Deinitialises the synchronisation code for the calling process. |
| This has to be called after successful initialisation and after |
| any other call of this module has finished. |
| |
| @Return PVRSRV_OK if the deinitialisation was successful |
| PVRSRV_ERROR_xxx if an error occurred |
| */ |
| /*****************************************************************************/ |
| IMG_EXPORT PVRSRV_ERROR |
| PVRSRVSyncDeinitI(void); |
| #define PVRSRVSyncDeinit(void) \ |
| PVRSRVSyncDeinitI(void) |
| |
| |
| /*************************************************************************/ /*! |
| @Function PVRSRVTimelineCreate |
| |
| @Description Allocate a new synchronisation timeline. |
| The timeline value is initialised to zero. |
| |
| @Input pszTimelineName String to be used to annotate timeline |
| (for debug) |
| |
| @Output hTimeline Handle to created timeline |
| |
| @Return PVRSRV_OK if the timeline was successfully created |
| PVRSRV_ERROR_NOMEM if there was insufficient memory to |
| create the new timeline |
| */ |
| /*****************************************************************************/ |
| IMG_EXPORT PVRSRV_ERROR |
| PVRSRVTimelineCreateI(PVRSRV_TIMELINE *phTimeline, |
| const IMG_CHAR *pszTimelineName |
| PVR_DBG_FILELINE_PARAM); |
| #define PVRSRVTimelineCreate(hTimeline, pszTimelineName) \ |
| PVRSRVTimelineCreateI( (hTimeline), (pszTimelineName) \ |
| PVR_DBG_FILELINE) |
| |
| /*************************************************************************/ /*! |
| @Function PVRSRVTimelineDestroy |
| |
| @Description Destroy a timeline |
| If the timeline has no outstanding checks or updates on |
| it then it will be destroyed immediately. |
| If there are outstanding checks or updates, the timeline |
| will be flagged for destruction once all outstanding |
| checks and updates are destroyed. |
| A timeline marked for destruction may not have further |
| checks or updates created for it. |
| |
| @Input hTimeline The timeline to destroy |
| |
| @Return PVRSRV_OK if a valid active timeline was specified |
| PVRSRV_ERROR_INVALID_PARAMS if an unrecognised timeline |
| was specified |
| */ |
| /*****************************************************************************/ |
| IMG_EXPORT PVRSRV_ERROR |
| PVRSRVTimelineDestroyI(PVRSRV_TIMELINE hTimeline |
| PVR_DBG_FILELINE_PARAM); |
| #define PVRSRVTimelineDestroy(hTimeline) \ |
| PVRSRVTimelineDestroyI( (hTimeline) PVR_DBG_FILELINE) |
| |
| /*************************************************************************/ /*! |
| @Function PVRSRVSWTimelineCreate |
| |
| @Description Allocate a new software timeline for synchronisation. |
| Software timelines are different to timelines created with |
| PVRSRVTimelineCreate in that they represent a strictly ordered |
| sequence of events *progressed on the CPU* rather than the GPU |
| |
| The sequence of events has to be modelled by the application |
| itself: |
| 1. First the application creates a SW timeline (this call) |
| 2. After creating some workload on the CPU the application can |
| create a fence for it by calling PVRSRVSWFenceCreate and pass |
| in a software timeline. |
| 3. When the workload finished and the application wants |
| to signal potential waiters that work has finished, it can call |
| PVRSRVSWTimelineAdvance which will signal the oldest fence |
| on this software timeline |
| |
| Destroy with PVRSRVTimelineDestroy |
| |
| @Input pszSWTimelineName String to be used to annotate the software |
| timeline (for debug) |
| |
| @Output phSWTimeline Handle to created software timeline |
| |
| @Return PVRSRV_OK if the timeline was successfully created |
| PVRSRV_ERROR_xxx if an error occurred |
| */ |
| /*****************************************************************************/ |
| IMG_EXPORT PVRSRV_ERROR |
| PVRSRVSWTimelineCreateI(PVRSRV_TIMELINE *phSWTimeline, |
| const IMG_CHAR *pszSWTimelineName |
| PVR_DBG_FILELINE_PARAM); |
| #define PVRSRVSWTimelineCreate(hSWTimeline, pszSWTimelineName) \ |
| PVRSRVSWTimelineCreateI( (hSWTimeline), (pszSWTimelineName) \ |
| PVR_DBG_FILELINE) |
| |
| /*************************************************************************/ /*! |
| @Function PVRSRVFenceWait |
| |
| @Description Wait for a fence checkpoint to be signalled. |
| |
| @Input hFence Handle to the fence |
| |
| @Input ui32TimeoutInMs Maximum time to wait (in milliseconds) |
| |
| @Return PVRSRV_OK once the fence has been passed (all component |
| checkpoints have either signalled or errored) |
| PVRSRV_ERROR_TIMEOUT if the poll has exceeded the timeout |
| PVRSRV_ERROR_INVALID_PARAMS if an unrecognised fence was specified |
| */ |
| /*****************************************************************************/ |
| IMG_EXPORT PVRSRV_ERROR |
| PVRSRVFenceWaitI(PVRSRV_FENCE hFence, |
| IMG_UINT32 ui32TimeoutInMs |
| PVR_DBG_FILELINE_PARAM); |
| #define PVRSRVFenceWait(hFence, ui32TimeoutInMs) \ |
| PVRSRVFenceWaitI( (hFence), (ui32TimeoutInMs) \ |
| PVR_DBG_FILELINE) |
| |
| /*************************************************************************/ /*! |
| @Function PVRSRVFenceDup |
| |
| @Description Create a duplicate of the specified fence. |
| The original fence will remain unchanged. |
| The new fence will be an exact copy of the original and |
| will reference the same timeline checkpoints as the |
| source fence at the time of its creation. |
| Any OSNativeSyncs attached to the original fence will also |
| be attached to the duplicated fence. |
| NB. If the source fence is subsequently merged or deleted |
| it will then differ from the dup'ed copy (which will |
| be unaffected). |
| |
| @Input hSourceFence Handle of the fence to be duplicated |
| |
| @Output phOutputFence Handle of newly created duplicate fence |
| |
| @Return PVRSRV_OK if the duplicate fence was successfully created |
| PVRSRV_ERROR_INVALID_PARAMS if an unrecognised fence was specified |
| PVRSRV_ERROR_NOMEM if there was insufficient memory to create |
| the new fence |
| */ |
| /*****************************************************************************/ |
| IMG_EXPORT PVRSRV_ERROR |
| PVRSRVFenceDupI(PVRSRV_FENCE hSourceFence, |
| PVRSRV_FENCE *phOutputFence |
| PVR_DBG_FILELINE_PARAM); |
| #define PVRSRVFenceDup(hSourceFence, phOutputFence) \ |
| PVRSRVFenceDupI( (hSourceFence), (phOutputFence) \ |
| PVR_DBG_FILELINE) |
| |
| |
| /*************************************************************************/ /*! |
| @Function PVRSRVFenceMerge |
| |
| @Description Merges two fences to create a new third fence. |
| The original fences will remain unchanged. |
| The new fence will be merge of two original fences and |
| will reference the same timeline checkpoints as the |
| two source fences with the exception that where each |
| source fence contains a checkpoint for the same timeline |
| the output fence will only contain the later of the two |
| checkpoints. |
| Any OSNativeSyncs attached to the original fences will also |
| be attached to the resultant merged fence. |
| If only one of the two source fences is valid, the function |
| shall simply return a duplicate of the valid fence with no |
| error indicated. |
| NB. If the source fences are subsequently merged or deleted |
| they will then differ from the merged copy (which will |
| be unaffected). |
| |
| @Input hSourceFence1 Handle of the 1st fence to be merged |
| |
| @Input hSourceFence2 Handle of the 2nd fence to be merged |
| |
| @Input pszFenceName Name of the created merged fence |
| |
| @Output phOutputFence Handle of the newly created merged fence |
| |
| @Return PVRSRV_OK if the merged fence was successfully created |
| PVRSRV_ERROR_INVALID_PARAMS if both source fences are unrecognised |
| PVRSRV_ERROR_NOMEM if there was insufficient memory to create |
| the new merged fence |
| */ |
| /*****************************************************************************/ |
| IMG_EXPORT PVRSRV_ERROR |
| PVRSRVFenceMergeI(PVRSRV_FENCE hSourceFence1, |
| PVRSRV_FENCE hSourceFence2, |
| const IMG_CHAR *pszFenceName, |
| PVRSRV_FENCE *phOutputFence |
| PVR_DBG_FILELINE_PARAM); |
| #define PVRSRVFenceMerge(hSourceFence1, hSourceFence2, pszFenceName, phOutputFence) \ |
| PVRSRVFenceMergeI( (hSourceFence1), (hSourceFence2), (pszFenceName), (phOutputFence) \ |
| PVR_DBG_FILELINE) |
| |
| |
| /*************************************************************************/ /*! |
| @Function PVRSRVFenceAccumulate |
| |
| @Description Same as PVRSRVFenceMerge but destroys the input fences. |
| If only one of the two source fences is valid, the function |
| shall simply return the valid fence rather than performing |
| a merge. |
| |
| @Input hSourceFence1 Handle of the 1st fence to be accumulated |
| |
| @Input hSourceFence2 Handle of the 2nd fence to be accumulated |
| |
| @Input pszFenceName Name of the created accumulated fence |
| |
| @Output phOutputFence Handle of the newly created fence |
| |
| @Return PVRSRV_OK if the accumulated fence was successfully created or |
| returned |
| PVRSRV_ERROR_INVALID_PARAMS if both source fences are unrecognised |
| PVRSRV_ERROR_NOMEM if there was insufficient memory to create |
| the new merged fence |
| */ |
| /*****************************************************************************/ |
| IMG_EXPORT PVRSRV_ERROR |
| PVRSRVFenceAccumulateI(PVRSRV_FENCE hSourceFence1, |
| PVRSRV_FENCE hSourceFence2, |
| const IMG_CHAR *pszFenceName, |
| PVRSRV_FENCE *phOutputFence |
| PVR_DBG_FILELINE_PARAM); |
| #define PVRSRVFenceAccumulate(hSourceFence1, hSourceFence2, pszFenceName, phOutputFence) \ |
| PVRSRVFenceAccumulateI( (hSourceFence1), (hSourceFence2), (pszFenceName), (phOutputFence) \ |
| PVR_DBG_FILELINE) |
| |
| |
| /*************************************************************************/ /*! |
| @Function PVRSRVFenceDump |
| |
| @Description Dumps debug information about the specified fence. |
| |
| @Input hFence Handle to the fence |
| |
| @Return PVRSRV_OK if a valid fence was specified |
| PVRSRV_ERROR_INVALID_PARAMS if an invalid fence was specified |
| */ |
| /*****************************************************************************/ |
| IMG_EXPORT PVRSRV_ERROR |
| PVRSRVFenceDumpI(PVRSRV_FENCE hFence |
| PVR_DBG_FILELINE_PARAM); |
| #define PVRSRVFenceDump(hFence) \ |
| PVRSRVFenceDumpI( (hFence) PVR_DBG_FILELINE) |
| |
| /*************************************************************************/ /*! |
| @Function PVRSRVFenceDestroy |
| |
| @Description Destroy a fence. |
| The fence will be destroyed immediately if its refCount |
| is now 0, otherwise it will be destroyed once all references |
| to it have been dropped. |
| |
| @Input hFence Handle to the fence |
| |
| @Return PVRSRV_OK if the fence was successfully marked for |
| destruction (now or later) |
| PVRSRV_ERROR_INVALID_PARAMS if an unrecognised fence was specified |
| */ |
| /*****************************************************************************/ |
| IMG_EXPORT PVRSRV_ERROR |
| PVRSRVFenceDestroyI(PVRSRV_FENCE hFence |
| PVR_DBG_FILELINE_PARAM); |
| #define PVRSRVFenceDestroy(hFence) \ |
| PVRSRVFenceDestroyI( (hFence) PVR_DBG_FILELINE) |
| |
| /*************************************************************************/ /*! |
| @Function PVRSRVIsTimelineValid |
| |
| @Description Checks whether the passed timeline handle has been set to an |
| invalid value. |
| Used to find out if the timeline can be passed into fence |
| sync functions. |
| |
| @Return IMG_TRUE if the passed timeline is valid, IMG_FALSE if invalid |
| */ |
| /*****************************************************************************/ |
| IMG_BOOL PVRSRVIsTimelineValid(PVRSRV_TIMELINE iTimeline); |
| |
| /*************************************************************************/ /*! |
| @Function PVRSRVIsFenceValid |
| |
| @Description Checks whether the passed fence handle has been set to an |
| invalid value. |
| Used to find out if the fence can be passed into fence |
| sync functions. |
| |
| @Return IMG_TRUE if the passed fence is valid, IMG_FALSE if invalid |
| */ |
| /*****************************************************************************/ |
| IMG_BOOL PVRSRVIsFenceValid(PVRSRV_FENCE iFence); |
| |
| |
| #if defined (__cplusplus) |
| } |
| #endif |
| #endif /* PVRSRV_SYNC_UM_H */ |
