drivers/staging/imgtec/rogue/sync_checkpoint.h

   1 /*************************************************************************/ /*!
   2 @File
   3 @Title          Synchronisation checkpoint interface header
   4 @Copyright      Copyright (c) Imagination Technologies Ltd. All Rights Reserved
   5 @Description    Defines the client side interface for synchronisation
   6 @License        Dual MIT/GPLv2
   7
   8 The contents of this file are subject to the MIT license as set out below.
   9
  10 Permission is hereby granted, free of charge, to any person obtaining a copy
  11 of this software and associated documentation files (the "Software"), to deal
  12 in the Software without restriction, including without limitation the rights
  13 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  14 copies of the Software, and to permit persons to whom the Software is
  15 furnished to do so, subject to the following conditions:
  16
  17 The above copyright notice and this permission notice shall be included in
  18 all copies or substantial portions of the Software.
  19
  20 Alternatively, the contents of this file may be used under the terms of
  21 the GNU General Public License Version 2 ("GPL") in which case the provisions
  22 of GPL are applicable instead of those above.
  23
  24 If you wish to allow use of your version of this file only under the terms of
  25 GPL, and not to allow others to use your version of this file under the terms
  26 of the MIT license, indicate your decision by deleting the provisions above
  27 and replace them with the notice and other provisions required by GPL as set
  28 out in the file called "GPL-COPYING" included in this distribution. If you do
  29 not delete the provisions above, a recipient may use your version of this file
  30 under the terms of either the MIT license or GPL.
  31
  32 This License is also included in this distribution in the file called
  33 "MIT-COPYING".
  34
  35 EXCEPT AS OTHERWISE STATED IN A NEGOTIATED AGREEMENT: (A) THE SOFTWARE IS
  36 PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
  37 BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  38 PURPOSE AND NONINFRINGEMENT; AND (B) IN NO EVENT SHALL THE AUTHORS OR
  39 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  40 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  41 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  42 */ /**************************************************************************/
  43
  44 #ifndef _SYNC_CHECKPOINT_
  45 #define _SYNC_CHECKPOINT_
  46
  47 #include "img_types.h"
  48 #include "pvrsrv_error.h"
  49 #include "pvrsrv_sync_km.h"
  50 #include "pdumpdefs.h"
  51 #include "dllist.h"
  52 #include "pvr_debug.h"
  53
  54 #include "device_connection.h"
  55
  56 typedef struct _PVRSRV_DEVICE_NODE_ PVRSRV_DEVICE_NODE;
  57
  58 typedef struct _SYNC_CHECKPOINT_CONTEXT *PSYNC_CHECKPOINT_CONTEXT;
  59
  60 typedef struct _SYNC_CHECKPOINT *PSYNC_CHECKPOINT;
  61
  62
  63 /*************************************************************************/ /*!
  64 @Function       SyncCheckpointContextCreate
  65
  66 @Description    Create a new synchronisation checkpoint context
  67
  68 @Input          psDevNode                 Device node
  69
  70 @Output         ppsSyncCheckpointContext  Handle to the created synchronisation
  71                                           checkpoint context
  72
  73 @Return         PVRSRV_OK if the synchronisation checkpoint context was
  74                 successfully created
  75 */
  76 /*****************************************************************************/
  77 PVRSRV_ERROR
  78 SyncCheckpointContextCreate(PVRSRV_DEVICE_NODE *psDevNode,
  79                             PSYNC_CHECKPOINT_CONTEXT *ppsSyncCheckpointContext);
  80
  81 /*************************************************************************/ /*!
  82 @Function       SyncCheckpointContextDestroy
  83
  84 @Description    Destroy a synchronisation checkpoint context
  85
  86 @Input          psSyncCheckpointContext  Handle to the synchronisation
  87                                          checkpoint context to destroy
  88
  89 @Return         PVRSRV_OK if the synchronisation checkpoint context was
  90                 successfully destroyed.
  91                 PVRSRV_ERROR_UNABLE_TO_DESTROY_CONTEXT if the context still
  92                 has sync checkpoints defined
  93 */
  94 /*****************************************************************************/
  95 PVRSRV_ERROR
  96 SyncCheckpointContextDestroy(PSYNC_CHECKPOINT_CONTEXT psSyncCheckpointContext);
  97
  98 /*************************************************************************/ /*!
  99 @Function       SyncCheckpointAlloc
 100
 101 @Description    Allocate a new synchronisation checkpoint on the specified
 102                 synchronisation checkpoint context
 103
 104 @Input          hSyncCheckpointContext  Handle to the synchronisation
 105                                         checkpoint context
 106
 107 @Input          pszClassName            Sync checkpoint source annotation
 108                                         (will be truncated to at most
 109                                          SYNC_CHECKPOINT_NAME_SIZE chars)
 110
 111 @Output         ppsSyncCheckpoint       Created synchronisation checkpoint
 112
 113 @Return         PVRSRV_OK if the synchronisation checkpoint was
 114                 successfully created
 115 */
 116 /*****************************************************************************/
 117 PVRSRV_ERROR
 118 SyncCheckpointAlloc(PSYNC_CHECKPOINT_CONTEXT psSyncContext,
 119                     const IMG_CHAR *pszCheckpointName,
 120                     PSYNC_CHECKPOINT *ppsSyncCheckpoint);
 121
 122 /*************************************************************************/ /*!
 123 @Function       SyncCheckpointFree
 124
 125 @Description    Free a synchronization checkpoint
 126                 The reference count held for the synchronization checkpoint
 127                 is decremented - if it has becomes zero, it is also freed.
 128
 129 @Input          psSyncCheckpoint        The synchronisation checkpoint to free
 130
 131 @Return         None
 132 */
 133 /*****************************************************************************/
 134 void
 135 SyncCheckpointFree(PSYNC_CHECKPOINT psSyncCheckpoint);
 136
 137 /*************************************************************************/ /*!
 138 @Function       SyncCheckpointSignal
 139
 140 @Description    Signal the synchronisation checkpoint
 141
 142 @Input          psSyncCheckpoint        The synchronisation checkpoint to signal
 143
 144 @Return         None
 145 */
 146 /*****************************************************************************/
 147 void
 148 SyncCheckpointSignal(PSYNC_CHECKPOINT psSyncCheckpoint);
 149
 150 /*************************************************************************/ /*!
 151 @Function       SyncCheckpointError
 152
 153 @Description    Error the synchronisation checkpoint
 154
 155 @Input          psSyncCheckpoint        The synchronisation checkpoint to error
 156
 157 @Return         None
 158 */
 159 /*****************************************************************************/
 160 void
 161 SyncCheckpointError(PSYNC_CHECKPOINT psSyncCheckpoint);
 162
 163 /*************************************************************************/ /*!
 164 @Function       SyncCheckpointErrorFromUFO
 165
 166 @Description    Error the synchronisation checkpoint which has the
 167                 given UFO firmware address
 168
 169 @Input          hSyncCheckpointContext  Handle to the synchronisation checkpoint
 170                                         context to which the checkpoint belongs
 171
 172 @Input          ui32FwAddr              The firmware address of the sync
 173                                         checkpoint to be errored
 174
 175 @Return         None
 176 */
 177 /*****************************************************************************/
 178 void
 179 SyncCheckpointErrorFromUFO(PSYNC_CHECKPOINT_CONTEXT psSyncCheckpointContext,
 180                                                    IMG_UINT32 ui32FwAddr);
 181
 182 /*************************************************************************/ /*!
 183 @Function       SyncCheckpointIsSignalled
 184
 185 @Description    Returns IMG_TRUE if the synchronisation checkpoint is
 186                 signalled or errored
 187
 188 @Input          psSyncCheckpoint        The synchronisation checkpoint to test
 189
 190 @Return         None
 191 */
 192 /*****************************************************************************/
 193 IMG_BOOL
 194 SyncCheckpointIsSignalled(PSYNC_CHECKPOINT psSyncCheckpoint);
 195
 196 /*************************************************************************/ /*!
 197 @Function       SyncCheckpointIsErrored
 198
 199 @Description    Returns IMG_TRUE if the synchronisation checkpoint is
 200                 errored
 201
 202 @Input          psSyncCheckpoint        The synchronisation checkpoint to test
 203
 204 @Return         None
 205 */
 206 /*****************************************************************************/
 207 IMG_BOOL
 208 SyncCheckpointIsErrored(PSYNC_CHECKPOINT psSyncCheckpoint);
 209
 210 /*************************************************************************/ /*!
 211 @Function       SyncCheckpointTakeRef
 212
 213 @Description    Take a reference on a synchronisation checkpoint
 214
 215 @Input          psSyncCheckpoint        Synchronisation checkpoint to take a
 216                                         reference on
 217
 218 @Return         PVRSRV_OK if a reference was taken on the synchronisation
 219                 primitive
 220 */
 221 /*****************************************************************************/
 222 PVRSRV_ERROR
 223 SyncCheckpointTakeRef(PSYNC_CHECKPOINT psSyncCheckpoint);
 224
 225 /*************************************************************************/ /*!
 226 @Function       SyncCheckpointDropRef
 227
 228 @Description    Drop a reference on a synchronisation checkpoint
 229
 230 @Input          psSyncCheckpoint        Synchronisation checkpoint to drop a
 231                                         reference on
 232
 233 @Return         PVRSRV_OK if a reference was dropped on the synchronisation
 234                 primitive
 235 */
 236 /*****************************************************************************/
 237 PVRSRV_ERROR
 238 SyncCheckpointDropRef(PSYNC_CHECKPOINT psSyncCheckpoint);
 239
 240 /*************************************************************************/ /*!
 241 @Function       SyncCheckpointResolveFence
 242
 243 @Description    Resolve a fence, returning a list of the sync checkpoints
 244                 that fence contains.
 245                 This function in turn calls a function provided by the
 246                 OS native sync implementation.
 247
 248 @Input          hFence                  The fence to be resolved
 249
 250 @Output         pui32NumSyncCheckpoints The number of sync checkpoints the
 251                                         fence contains. Can return 0 if
 252                                         passed a null (-1) fence.
 253
 254 @Output         psSyncCheckpoints       List of sync checkpoints the fence
 255                                         contains
 256
 257 @Return         PVRSRV_OK if a valid fence was provided.
 258                 PVRSRV_ERROR_SYNC_NATIVESYNC_NOT_REGISTERED if the OS native
 259                 sync has not registered a callback function.
 260 */
 261 /*****************************************************************************/
 262 PVRSRV_ERROR
 263 SyncCheckpointResolveFence(PVRSRV_FENCE_KM hFence, IMG_UINT32 *pui32NumSyncCheckpoints, PSYNC_CHECKPOINT *psSyncCheckpoints);
 264
 265 /*************************************************************************/ /*!
 266 @Function       SyncCheckpointCreateFence
 267
 268 @Description    Create a fence containing a single sync checkpoint.
 269                 Return the fence and a ptr to sync checkpoint it contains.
 270                 This function in turn calls a function provided by the
 271                 OS native sync implementation.
 272
 273 @Input          pszFenceName            String to assign to the new fence
 274                                         (for debugging purposes)
 275
 276 @Input          hTimeline               Timeline on which the new fence is
 277                                         to be created
 278
 279 @Output         phNewFence              The newly created fence
 280
 281 @Output         psNewSyncCheckpoint     The sync checkpoint contained in
 282                                         the new fence
 283
 284 @Return         PVRSRV_OK if a valid fence was provided.
 285                 PVRSRV_ERROR_SYNC_NATIVESYNC_NOT_REGISTERED if the OS native
 286                 sync has not registered a callback function.
 287 */
 288 /*****************************************************************************/
 289 PVRSRV_ERROR
 290 SyncCheckpointCreateFence(const IMG_CHAR *pszFenceName, PVRSRV_TIMELINE_KM hTimeline, PVRSRV_FENCE_KM *phNewFence, PSYNC_CHECKPOINT *psNewSyncCheckpoint);
 291
 292 #endif  /* _SYNC_CHECKPOINT_ */
 293