drivers/staging/imgtec/rogue/htbserver.h

   1 /*************************************************************************/ /*!
   2 @File           htbserver.h
   3 @Title          Host Trace Buffer server implementation.
   4 @Copyright      Copyright (c) Imagination Technologies Ltd. All Rights Reserved
   5
   6 @Description    Host Trace Buffer provides a mechanism to log Host events to a
   7                 buffer in a similar way to the Firmware Trace mechanism.
   8                 Host Trace Buffer logs data using a Transport Layer buffer.
   9                 The Transport Layer and pvrtld tool provides the mechanism to
  10                 retrieve the trace data.
  11
  12                 A Host Trace can be merged with a corresponding Firmware Trace.
  13                 This is achieved by inserting synchronisation data into both
  14                 traces and post processing to merge them.
  15
  16                 The FW Trace will contain a "Sync Partition Marker". This is
  17                 updated every time the RGX is brought out of reset (RGX clock
  18                 timestamps reset at this point) and is repeated when the FW
  19                 Trace buffer wraps to ensure there is always at least 1
  20                 partition marker in the Firmware Trace buffer whenever it is
  21                 read.
  22
  23                 The Host Trace will contain corresponding "Sync Partition
  24                 Markers" - #HTBSyncPartitionMarker(). Each partition is then
  25                 subdivided into "Sync Scale" sections - #HTBSyncScale(). The
  26                 "Sync Scale" data allows the timestamps from the two traces to
  27                 be correlated. The "Sync Scale" data is updated as part of the
  28                 standard RGX time correlation code (rgxtimecorr.c) and is
  29                 updated periodically including on power and clock changes.
  30
  31 @License        Dual MIT/GPLv2
  32
  33 The contents of this file are subject to the MIT license as set out below.
  34
  35 Permission is hereby granted, free of charge, to any person obtaining a copy
  36 of this software and associated documentation files (the "Software"), to deal
  37 in the Software without restriction, including without limitation the rights
  38 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  39 copies of the Software, and to permit persons to whom the Software is
  40 furnished to do so, subject to the following conditions:
  41
  42 The above copyright notice and this permission notice shall be included in
  43 all copies or substantial portions of the Software.
  44
  45 Alternatively, the contents of this file may be used under the terms of
  46 the GNU General Public License Version 2 ("GPL") in which case the provisions
  47 of GPL are applicable instead of those above.
  48
  49 If you wish to allow use of your version of this file only under the terms of
  50 GPL, and not to allow others to use your version of this file under the terms
  51 of the MIT license, indicate your decision by deleting the provisions above
  52 and replace them with the notice and other provisions required by GPL as set
  53 out in the file called "GPL-COPYING" included in this distribution. If you do
  54 not delete the provisions above, a recipient may use your version of this file
  55 under the terms of either the MIT license or GPL.
  56
  57 This License is also included in this distribution in the file called
  58 "MIT-COPYING".
  59
  60 EXCEPT AS OTHERWISE STATED IN A NEGOTIATED AGREEMENT: (A) THE SOFTWARE IS
  61 PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
  62 BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  63 PURPOSE AND NONINFRINGEMENT; AND (B) IN NO EVENT SHALL THE AUTHORS OR
  64 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  65 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  66 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  67 */ /**************************************************************************/
  68
  69 #ifndef __HTBSERVER_H__
  70 #define __HTBSERVER_H__
  71
  72 #include "img_types.h"
  73 #include "pvrsrv_error.h"
  74 #include "pvrsrv.h"
  75 #include "htbuffer.h"
  76
  77
  78 /************************************************************************/ /*!
  79  @Function      HTBIDeviceCreate
  80  @Description   Initialisation actions for HTB at device creation.
  81
  82  @Input         psDeviceNode    Reference to the device node in context
  83
  84  @Return        eError          Internal services call returned eError error
  85                                 number
  86 */ /**************************************************************************/
  87 PVRSRV_ERROR
  88 HTBDeviceCreate(
  89                 PVRSRV_DEVICE_NODE *psDeviceNode
  90 );
  91
  92
  93 /************************************************************************/ /*!
  94  @Function      HTBIDeviceDestroy
  95  @Description   De-initialisation actions for HTB at device destruction.
  96
  97  @Input         psDeviceNode    Reference to the device node in context
  98
  99 */ /**************************************************************************/
 100 void
 101 HTBDeviceDestroy(
 102                 PVRSRV_DEVICE_NODE *psDeviceNode
 103 );
 104
 105
 106 /************************************************************************/ /*!
 107  @Function      HTBDeInit
 108  @Description   Close the Host Trace Buffer and free all resources
 109
 110  @Return        eError          Internal services call returned eError error
 111                                 number
 112 */ /**************************************************************************/
 113 PVRSRV_ERROR
 114 HTBDeInit( void );
 115
 116
 117 /*************************************************************************/ /*!
 118  @Function      HTBConfigureKM
 119  @Description   Configure or update the configuration of the Host Trace Buffer
 120
 121  @Input         ui32NameSize    Size of the pszName string
 122
 123  @Input         pszName         Name to use for the underlying data buffer
 124
 125  @Input         ui32BufferSize  Size of the underlying data buffer
 126
 127  @Return        eError          Internal services call returned eError error
 128                                 number
 129 */ /**************************************************************************/
 130 PVRSRV_ERROR
 131 HTBConfigureKM(
 132                 IMG_UINT32 ui32NameSize,
 133                 const IMG_CHAR * pszName,
 134                 const IMG_UINT32 ui32BufferSize
 135 );
 136
 137
 138 /*************************************************************************/ /*!
 139  @Function      HTBControlKM
 140  @Description   Update the configuration of the Host Trace Buffer
 141
 142  @Input         ui32NumFlagGroups Number of group enable flags words
 143
 144  @Input         aui32GroupEnable  Flags words controlling groups to be logged
 145
 146  @Input         ui32LogLevel    Log level to record
 147
 148  @Input         ui32EnablePID   PID to enable logging for a specific process
 149
 150  @Input         eLogMode        Enable logging for all or specific processes,
 151
 152  @Input         eOpMode         Control the behaviour of the data buffer
 153
 154  @Return        eError          Internal services call returned eError error
 155                                 number
 156 */ /**************************************************************************/
 157 PVRSRV_ERROR
 158 HTBControlKM(
 159         const IMG_UINT32 ui32NumFlagGroups,
 160         const IMG_UINT32 * aui32GroupEnable,
 161         const IMG_UINT32 ui32LogLevel,
 162         const IMG_UINT32 ui32EnablePID,
 163         const HTB_LOGMODE_CTRL eLogMode,
 164         const HTB_OPMODE_CTRL eOpMode
 165 );
 166
 167
 168 /*************************************************************************/ /*!
 169  @Function      HTBSyncPartitionMarker
 170  @Description   Write an HTB sync partition marker to the HTB log
 171
 172  @Input         ui33Marker      Marker value
 173
 174 */ /**************************************************************************/
 175 void
 176 HTBSyncPartitionMarker(
 177         const IMG_UINT32 ui32Marker
 178 );
 179
 180
 181 /*************************************************************************/ /*!
 182  @Function      HTBSyncScale
 183  @Description   Write FW-Host synchronisation data to the HTB log when clocks
 184                 change or are re-calibrated
 185
 186  @Input         bLogValues      IMG_TRUE if value should be immediately written
 187                                 out to the log
 188
 189  @Input         ui32OSTS        OS Timestamp
 190
 191  @Input         ui32CRTS        Rogue timestamp
 192
 193  @Input         ui32CalcClkSpd  Calculated clock speed
 194
 195 */ /**************************************************************************/
 196 void
 197 HTBSyncScale(
 198         const IMG_BOOL bLogValues,
 199         const IMG_UINT64 ui64OSTS,
 200         const IMG_UINT64 ui64CRTS,
 201         const IMG_UINT32 ui32CalcClkSpd
 202 );
 203
 204
 205 /*************************************************************************/ /*!
 206  @Function      HTBLogKM
 207  @Description   Record a Host Trace Buffer log event
 208
 209  @Input         PID             The PID of the process the event is associated
 210                                 with. This is provided as an argument rather
 211                                 than querying internally so that events associated
 212                                 with a particular process, but performed by
 213                                 another can be logged correctly.
 214
 215  @Input         ui32TimeStamp   The timestamp to be associated with this log event
 216
 217  @Input         SF              The log event ID
 218
 219  @Input         ...             Log parameters
 220
 221  @Return        PVRSRV_OK       Success.
 222
 223 */ /**************************************************************************/
 224 PVRSRV_ERROR
 225 HTBLogKM(
 226                 IMG_UINT32 PID,
 227                 IMG_UINT32 ui32TimeStamp,
 228                 HTB_LOG_SFids SF,
 229                 IMG_UINT32 ui32NumArgs,
 230                 IMG_UINT32 * aui32Args
 231 );
 232
 233
 234 #endif /* __HTBSERVER_H__ */
 235
 236 /* EOF */
 237