drivers/gpu/rogue_m/services/server/include/pmr.h

   1 /**************************************************************************/ /*!
   2 @File
   3 @Title          Physmem (PMR) abstraction
   4 @Copyright      Copyright (c) Imagination Technologies Ltd. All Rights Reserved
   5 @Description    Part of the memory management.  This module is responsible for
   6                 the "PMR" abstraction.  A PMR (Physical Memory Resource)
   7                 represents some unit of physical memory which is
   8                 allocated/freed/mapped/unmapped as an indivisible unit
   9                 (higher software levels provide an abstraction above that
  10                 to deal with dividing this down into smaller manageable units).
  11                 Importantly, this module knows nothing of virtual memory, or
  12                 of MMUs etc., with one excuseable exception.  We have the
  13                 concept of a "page size", which really means nothing in
  14                 physical memory, but represents a "contiguity quantum" such
  15                 that the higher level modules which map this memory are able
  16                 to verify that it matches the needs of the page size for the
  17                 virtual realm into which it is being mapped.
  18 @License        Dual MIT/GPLv2
  19
  20 The contents of this file are subject to the MIT license as set out below.
  21
  22 Permission is hereby granted, free of charge, to any person obtaining a copy
  23 of this software and associated documentation files (the "Software"), to deal
  24 in the Software without restriction, including without limitation the rights
  25 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  26 copies of the Software, and to permit persons to whom the Software is
  27 furnished to do so, subject to the following conditions:
  28
  29 The above copyright notice and this permission notice shall be included in
  30 all copies or substantial portions of the Software.
  31
  32 Alternatively, the contents of this file may be used under the terms of
  33 the GNU General Public License Version 2 ("GPL") in which case the provisions
  34 of GPL are applicable instead of those above.
  35
  36 If you wish to allow use of your version of this file only under the terms of
  37 GPL, and not to allow others to use your version of this file under the terms
  38 of the MIT license, indicate your decision by deleting the provisions above
  39 and replace them with the notice and other provisions required by GPL as set
  40 out in the file called "GPL-COPYING" included in this distribution. If you do
  41 not delete the provisions above, a recipient may use your version of this file
  42 under the terms of either the MIT license or GPL.
  43
  44 This License is also included in this distribution in the file called
  45 "MIT-COPYING".
  46
  47 EXCEPT AS OTHERWISE STATED IN A NEGOTIATED AGREEMENT: (A) THE SOFTWARE IS
  48 PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
  49 BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  50 PURPOSE AND NONINFRINGEMENT; AND (B) IN NO EVENT SHALL THE AUTHORS OR
  51 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  52 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  53 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  54 */ /***************************************************************************/
  55
  56 #ifndef _SRVSRV_PMR_H_
  57 #define _SRVSRV_PMR_H_
  58
  59 /* include/ */
  60 #include "img_types.h"
  61 #include "pdumpdefs.h"
  62 #include "pvrsrv_error.h"
  63 #include "pvrsrv_memallocflags.h"
  64 #include "devicemem_typedefs.h"                 /* Required for export DEVMEM_EXPORTCOOKIE */
  65
  66 /* services/include */
  67 #include "pdump.h"
  68
  69 /* services/server/include/ */
  70 #include "pmr_impl.h"
  71 #include "physheap.h"
  72 /* A typical symbolic address for physical memory may look like:
  73    :MEMORYSPACE:SUBSYS_NNNNNN_0X1234567890_XYZ.  That example is quite
  74    extreme, they are likely shorter than that.  We'll make the define
  75    here plentiful, however, note that this is _advisory_ not
  76    _mandatory_ - in other words, it's the allocator's responsibility
  77    to choose the amount of memory to set aside, and it's up to us to
  78    honour the size passed in by the caller.  i.e. this define is for
  79    GUIDANCE ONLY.
  80 */
  81 #define PMR_MAX_SYMBOLIC_ADDRESS_LENGTH_DEFAULT         (60)
  82 #define PMR_MAX_MEMSPACE_NAME_LENGTH_DEFAULT            (20)
  83 #define PMR_MAX_MEMSPNAME_SYMB_ADDR_LENGTH_DEFAULT      (PMR_MAX_SYMBOLIC_ADDRESS_LENGTH_DEFAULT + PMR_MAX_MEMSPACE_NAME_LENGTH_DEFAULT)
  84 #define PMR_MAX_PARAMSTREAM_FILENAME_LENGTH_DEFAULT (100)
  85 #define PMR_MAX_TRANSLATION_STACK_ALLOC                         (32)
  86
  87 typedef IMG_UINT64 PMR_BASE_T;
  88 typedef IMG_UINT64 PMR_SIZE_T;
  89 #define PMR_SIZE_FMTSPEC "0x%010llX"
  90 #define PMR_VALUE32_FMTSPEC "0x%08X"
  91 #define PMR_VALUE64_FMTSPEC "0x%016llX"
  92 typedef IMG_UINT32 PMR_LOG2ALIGN_T;
  93 typedef IMG_UINT64 PMR_PASSWORD_T;
  94
  95 typedef struct _PMR_ PMR;
  96 typedef struct _PMR_EXPORT_ PMR_EXPORT;
  97
  98 typedef struct _PMR_PAGELIST_ PMR_PAGELIST;
  99
 100 struct _PVRSRV_DEVICE_NODE_;
 101
 102 /*
 103  * PMRCreatePMR
 104  *
 105  * Not to be called directly, only via implementations of PMR
 106  * factories, e.g. in physmem_osmem.c, deviceclass.c, etc.
 107  *
 108  * Creates a PMR object, with callbacks and private data as per the
 109  * FuncTab/PrivData args.
 110  *
 111  * Note that at creation time the PMR must set in stone the "logical
 112  * size" and the "contiguity guarantee"
 113  *
 114  * Flags are also set at this time.  (T.B.D.  flags also immutable for
 115  * the life of the PMR?)
 116  *
 117  * Logical size is the amount of Virtual space this allocation would
 118  * take up when mapped.  Note that this does not have to be the same
 119  * as the actual physical size of the memory.  For example, consider
 120  * the sparsely allocated non-power-of-2 texture case.  In this
 121  * instance, the "logical size" would be the virtual size of the
 122  * rounded-up power-of-2 texture.  That some pages of physical memory
 123  * may not exist does not affect the logical size calculation.
 124  *
 125  * The PMR must also supply the "contiguity guarantee" which is the
 126  * finest granularity of alignment and size of physical pages that the
 127  * PMR will provide after LockSysPhysAddresses is called.  Note that
 128  * the calling code may choose to call PMRSysPhysAddr with a finer
 129  * granularity than this, for example if it were to map into a device
 130  * MMU with a smaller page size, and it's also OK for the PMR to
 131  * supply physical memory in larger chunks than this.  But
 132  * importantly, never the other way around.
 133  *
 134  * More precisely, the following inequality must be maintained
 135  * whenever mappings and/or physical addresses exist:
 136  *
 137  *       (device MMU page size) <= 2**(uiLog2ContiguityGuarantee) <= (actual contiguity of physical memory)
 138  *
 139  *
 140  * Note also that the implementation may supply pszPDumpFlavour and
 141  * pszPDumpDefaultMemspaceName, which are irrelevant where the PMR
 142  * implementation overrides the default symbolic name construction
 143  * routine.  Where the function pointer for PDump symbolic name
 144  * derivation is not overridden (i.e. IMG_NULL appears in the relevant
 145  * entry of the functab) and default implementation shall be used
 146  * which will copy the PDumpDefaultMemspaceName into the namespace
 147  * argument, and create the symbolic name by concatenating the
 148  * "PDumpFlavour" and a numeric representation of the PMR's serial
 149  * number.
 150  *
 151  * The implementation must guarantee that the storage for these two
 152  * strings, and the function table, are maintained, as copies are not
 153  * made, the pointer is simply stored.
 154  *
 155  * The function table will contain the following callbacks which may
 156  * be overridden by the PMR implementation:
 157  *
 158  * pfnLockPhysAddresses
 159  *
 160  *      Called when someone locks requests that Physical pages are to
 161  *      be locked down via the PMRLockSysPhysAddresses() API.  Note
 162  *      that if physical pages are prefaulted at PMR creation time and
 163  *      therefore static, it would not be necessary to override this
 164  *      function, in which case IMG_NULL may be supplied.
 165  *
 166  * pfnUnlockPhysAddresses
 167  *
 168  *      The reverse of pfnLockPhysAddresses.  Note that this should be
 169  *      IMG_NULL if and only if pfnLockPhysAddresses is IMG_NULL
 170  *
 171  * pfnSysPhysAddr
 172  *
 173  *      This function is mandatory.  This is the one which returns the
 174  *      system physical address for a given offset into this PMR.  The
 175  *      "lock" function will have been called, if overridden, before
 176  *      this function, thus the implementation should not increase any
 177  *      refcount when answering this call.  Refcounting, if necessary,
 178  *      should be done in the lock/unlock calls.  Refcounting would
 179  *      not be necessary in the prefaulted/static scenario, as the
 180  *      pmr.c abstraction will handle the refcounting for the whole
 181  *      PMR.
 182  *
 183  * pfnPDumpSymbolicAddr
 184  *
 185  *      Derives the PDump symbolic address for the given offset.  The
 186  *      default implementation will copy the PDumpDefaultMemspaceName
 187  *      into the namespace argument (or use SYSMEM if none was
 188  *      supplied), and create the symbolic name by concatenating the
 189  *      "PDumpFlavour" and a numeric representation of the PMR's
 190  *      serial number.
 191  *
 192  * pfnFinalize
 193  *
 194  *      Called when the PMR's refcount reaches zero and it gets
 195  *      destroyed.  This allows the implementation to free up any
 196  *      resource acquired during creation time.
 197  *
 198  */
 199 extern PVRSRV_ERROR
 200 PMRCreatePMR(PHYS_HEAP *psPhysHeap,
 201              PMR_SIZE_T uiLogicalSize,
 202              PMR_SIZE_T uiChunkSize,
 203              IMG_UINT32 ui32NumPhysChunks,
 204              IMG_UINT32 ui32NumVirtChunks,
 205              IMG_BOOL *pabMappingTable,
 206              PMR_LOG2ALIGN_T uiLog2ContiguityGuarantee,
 207              PMR_FLAGS_T uiFlags,
 208              const IMG_CHAR *pszPDumpFlavour,
 209              const PMR_IMPL_FUNCTAB *psFuncTab,
 210              PMR_IMPL_PRIVDATA pvPrivData,
 211              PMR **ppsPMRPtr,
 212              IMG_HANDLE *phPDumpAllocInfo,
 213              IMG_BOOL bForcePersistent);
 214
 215 /*
 216  * PMRLockSysPhysAddresses()
 217  *
 218  * Calls the relevant callback to lock down the system physical addresses of the memory that makes up the whole PMR.
 219  *
 220  * Before this call, it is not valid to use any of the information
 221  * getting APIs: PMR_Flags(), PMR_SysPhysAddr(),
 222  * PMR_PDumpSymbolicAddr() [ see note below about lock/unlock
 223  * semantics ]
 224  *
 225  * The caller of this function does not have to care about how the PMR
 226  * is implemented.  He only has to know that he is allowed access to
 227  * the physical addresses _after_ calling this function and _until_
 228  * calling PMRUnlockSysPhysAddresses().
 229  *
 230  *
 231  * Notes to callback implementers (authors of PMR Factories):
 232  *
 233  * Some PMR implementations will be such that the physical memory
 234  * exists for the lifetime of the PMR, with a static address, (and
 235  * normally flags and symbolic address are static too) and so it is
 236  * legal for a PMR implementation to not provide an implementation for
 237  * the lock callback.
 238  *
 239  * Some PMR implementation may wish to page memory in from secondary
 240  * storage on demand.  The lock/unlock callbacks _may_ be the place to
 241  * do this.  (more likely, there would be a separate API for doing
 242  * this, but this API provides a useful place to assert that it has
 243  * been done)
 244  */
 245
 246 extern PVRSRV_ERROR
 247 PMRLockSysPhysAddresses(PMR *psPMR,
 248                         IMG_UINT32 uiLog2DevPageSize);
 249
 250 extern PVRSRV_ERROR
 251 PMRLockSysPhysAddressesNested(PMR *psPMR,
 252                         IMG_UINT32 uiLog2DevPageSize,
 253                         IMG_UINT32 ui32NestingLevel);
 254
 255 /*
 256  * PMRUnlockSysPhysAddresses()
 257  *
 258  * the reverse of PMRLockSysPhysAddresses()
 259  */
 260 extern PVRSRV_ERROR
 261 PMRUnlockSysPhysAddresses(PMR *psPMR);
 262
 263 IMG_VOID PMRLock(void);
 264 IMG_VOID PMRUnlock(void);
 265 IMG_BOOL PMRIsLocked(void);
 266 IMG_BOOL PMRIsLockedByMe(void);
 267
 268 /*
 269  * PhysmemPMRExport()
 270  *
 271  * Given a PMR, creates a PMR "Export", which is a handle that
 272  * provides sufficient data to be able to "import" this PMR elsewhere.
 273  * The PMR Export is an object in its own right, whose existance
 274  * implies a reference on the PMR, thus the PMR cannot be destroyed
 275  * while the PMR Export exists.  The intention is that the PMR Export
 276  * will be wrapped in the devicemem layer by a cross process handle,
 277  * and some IPC by which to communicate the handle value and password
 278  * to other processes.  The receiving process is able to unwrap this
 279  * to gain access to the same PMR Export in this layer, and, via
 280  * PhysmemPMRImport(), obtain a reference to the original PMR.
 281  *
 282  * The caller receives, along with the PMR Export object, information
 283  * about the size and contiguity guarantee for the PMR, and also the
 284  * PMRs secret password, in order to authenticate the subsequent
 285  * import.
 286  *
 287  * N.B.  If you call PMRExportPMR() (and it succeeds), you are
 288  * promising to later call PMRUnexportPMR()
 289  */
 290 extern PVRSRV_ERROR
 291 PMRExportPMR(PMR *psPMR,
 292              PMR_EXPORT **ppsPMRExport,
 293              PMR_SIZE_T *puiSize,
 294              PMR_LOG2ALIGN_T *puiLog2Contig,
 295              PMR_PASSWORD_T *puiPassword);
 296
 297 /*
 298  * PMRMakeServerExportClientExport()
 299  *
 300  * This is a "special case" function for making a server export cookie
 301  * which went through the direct bridge into an export cookie that can
 302  * be passed through the client bridge.
 303  */
 304 PVRSRV_ERROR
 305 PMRMakeServerExportClientExport(DEVMEM_EXPORTCOOKIE *psPMRExportIn,
 306                                                                 PMR_EXPORT **ppsPMRExportPtr,
 307                                                                 PMR_SIZE_T *puiSize,
 308                                                                 PMR_LOG2ALIGN_T *puiLog2Contig,
 309                                                                 PMR_PASSWORD_T *puiPassword);
 310
 311 PVRSRV_ERROR
 312 PMRUnmakeServerExportClientExport(PMR_EXPORT *psPMRExport);
 313
 314 /*
 315  * PMRUnexporPMRt()
 316  *
 317  * The reverse of PMRExportPMR().  This causes the PMR to no
 318  * longer be exported.  If the PMR has already been imported, the
 319  * imported PMR reference will still be valid, but no further imports
 320  * will be possible.
 321  */
 322 extern PVRSRV_ERROR
 323 PMRUnexportPMR(PMR_EXPORT *psPMRExport);
 324
 325 /*
 326  * PMRImportPMR()
 327  *
 328  * Takes a PMR Export object, as obtained by PMRExportPMR(), and
 329  * obtains a reference to the original PMR.
 330  *
 331  * The password must match, and is assumed to have been (by whatever
 332  * means, IPC etc.) preserved intact from the former call to
 333  * PMRExportPMR()
 334  *
 335  * The size and contiguity arguments are entirely irrelevant for the
 336  * import, however they are verified in order to trap bugs.
 337  *
 338  * N.B.  If you call PhysmemPMRImport() (and it succeeds), you are
 339  * promising to later call PhysmemPMRUnimport()
 340  */
 341 extern PVRSRV_ERROR
 342 PMRImportPMR(PMR_EXPORT *psPMRExport,
 343              PMR_PASSWORD_T uiPassword,
 344              PMR_SIZE_T uiSize,
 345              PMR_LOG2ALIGN_T uiLog2Contig,
 346              PMR **ppsPMR);
 347
 348 /*
 349  * PMRUnimportPMR()
 350  *
 351  * releases the reference on the PMR as obtained by PMRImportPMR()
 352  */
 353 extern PVRSRV_ERROR
 354 PMRUnimportPMR(PMR *psPMR);
 355
 356 PVRSRV_ERROR
 357 PMRLocalImportPMR(PMR *psPMR,
 358                                   PMR **ppsPMR,
 359                                   IMG_DEVMEM_SIZE_T *puiSize,
 360                                   IMG_DEVMEM_ALIGN_T *puiAlign);
 361
 362 /*
 363  * Equivalent mapping functions when in kernel mode - TOOD: should
 364  * unify this and the PMRAcquireMMapArgs API with a suitable
 365  * abstraction
 366  */
 367 extern PVRSRV_ERROR
 368 PMRAcquireKernelMappingData(PMR *psPMR,
 369                             IMG_SIZE_T uiLogicalOffset,
 370                             IMG_SIZE_T uiSize,
 371                             IMG_VOID **ppvKernelAddressOut,
 372                             IMG_SIZE_T *puiLengthOut,
 373                             IMG_HANDLE *phPrivOut);
 374
 375 extern PVRSRV_ERROR
 376 PMRAcquireSparseKernelMappingData(PMR *psPMR,
 377                                   IMG_SIZE_T uiLogicalOffset,
 378                                   IMG_SIZE_T uiSize,
 379                                   IMG_VOID **ppvKernelAddressOut,
 380                                   IMG_SIZE_T *puiLengthOut,
 381                                   IMG_HANDLE *phPrivOut);
 382
 383 extern PVRSRV_ERROR
 384 PMRReleaseKernelMappingData(PMR *psPMR,
 385                             IMG_HANDLE hPriv);
 386
 387
 388 /*
 389  * PMR_ReadBytes()
 390  *
 391  * calls into the PMR implementation to read up to uiBufSz bytes,
 392  * returning the actual number read in *puiNumBytes
 393  *
 394  * this will read up to the end of the PMR, or the next symbolic name
 395  * boundary, or until the requested number of bytes is read, whichever
 396  * comes first
 397  *
 398  * In the case of sparse PMR's the caller doesn't know what offsets are
 399  * valid and which ones aren't so we will just write 0 to invalid offsets
 400  */
 401 extern PVRSRV_ERROR
 402 PMR_ReadBytes(PMR *psPMR,
 403               IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 404               IMG_UINT8 *pcBuffer,
 405               IMG_SIZE_T uiBufSz,
 406               IMG_SIZE_T *puiNumBytes);
 407
 408 /*
 409  * PMR_WriteBytes()
 410  *
 411  * calls into the PMR implementation to write up to uiBufSz bytes,
 412  * returning the actual number read in *puiNumBytes
 413  *
 414  * this will write up to the end of the PMR, or the next symbolic name
 415  * boundary, or until the requested number of bytes is written, whichever
 416  * comes first
 417  *
 418  * In the case of sparse PMR's the caller doesn't know what offsets are
 419  * valid and which ones aren't so we will just ignore data at invalid offsets
 420  */
 421 extern PVRSRV_ERROR
 422 PMR_WriteBytes(PMR *psPMR,
 423                            IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 424                IMG_UINT8 *pcBuffer,
 425                IMG_SIZE_T uiBufSz,
 426                IMG_SIZE_T *puiNumBytes);
 427
 428 /*
 429  * PMRRefPMR()
 430  *
 431  * Take a reference on the passed in PMR
 432  */
 433 extern IMG_VOID
 434 PMRRefPMR(PMR *psPMR);
 435
 436 /*
 437  * PMRUnrefPMR()
 438  *
 439  * This undoes a call to any of the PhysmemNew* family of APIs
 440  * (i.e. any PMR factory "constructor")
 441  *
 442  * This relinquishes a reference to the PMR, and, where the refcount
 443  * reaches 0, causes the PMR to be destroyed (calling the finalizer
 444  * callback on the PMR, if there is one)
 445  */
 446 extern PVRSRV_ERROR
 447 PMRUnrefPMR(PMR *psPMR);
 448
 449
 450 /*
 451  * PMR_Flags()
 452  *
 453  * Flags are static and guaranteed for the life of the PMR.  Thus this
 454  * function is idempotent and acquire/release semantics is not
 455  * required.
 456  *
 457  * Returns the flags as specified on the PMR.  The flags are to be
 458  * interpreted as mapping permissions
 459  */
 460 extern PVRSRV_ERROR
 461 PMR_Flags(const PMR *psPMR,
 462           PMR_FLAGS_T *puiMappingFlags);
 463
 464
 465 extern PVRSRV_ERROR
 466 PMR_LogicalSize(const PMR *psPMR,
 467                                 IMG_DEVMEM_SIZE_T *puiLogicalSize);
 468
 469 /*
 470  * PMR_SysPhysAddr()
 471  *
 472  * A note regarding Lock/Unlock semantics
 473  * ======================================
 474  *
 475  * PMR_SysPhysAddr may only be called after PMRLockSysPhysAddresses()
 476  * has been called.  The data returned may be used only until
 477  * PMRUnlockSysPhysAddresses() is called after which time the licence
 478  * to use the data is revoked and the information may be invalid.
 479  *
 480  * Given an offset, this function returns the device physical address of the
 481  * corresponding page in the PMR.  It may be called multiple times
 482  * until the address of all relevant pages has been determined.
 483  *
 484  * If caller only wants one physical address it is sufficient to pass in:
 485  * ui32Log2PageSize==0 and ui32NumOfPages==1
 486  */
 487 extern PVRSRV_ERROR
 488 PMR_DevPhysAddr(const PMR *psPMR,
 489                 IMG_UINT32 ui32Log2PageSize,
 490                 IMG_UINT32 ui32NumOfPages,
 491                 IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 492                 IMG_DEV_PHYADDR *psDevAddr,
 493                 IMG_BOOL *pbValid);
 494
 495 /*
 496  * PMR_CpuPhysAddr()
 497  *
 498  * See note above about Lock/Unlock semantics.
 499  *
 500  * Given an offset, this function returns the CPU physical address of the
 501  * corresponding page in the PMR.  It may be called multiple times
 502  * until the address of all relevant pages has been determined.
 503  *
 504  */
 505 extern PVRSRV_ERROR
 506 PMR_CpuPhysAddr(const PMR *psPMR,
 507                 IMG_UINT32 ui32Log2PageSize,
 508                 IMG_UINT32 ui32NumOfPages,
 509                 IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 510                 IMG_CPU_PHYADDR *psCpuAddrPtr,
 511                 IMG_BOOL *pbValid);
 512
 513 PVRSRV_ERROR
 514 PMRGetUID(PMR *psPMR,
 515                   IMG_UINT64 *pui64UID);
 516
 517 #if defined(PDUMP)
 518 /*
 519  * PMR_PDumpSymbolicAddr()
 520  *
 521  * Given an offset, returns the pdump memspace name and symbolic
 522  * address of the corresponding page in the PMR.
 523  *
 524  * Note that PDump memspace names and symbolic addresses are static
 525  * and valid for the lifetime of the PMR, therefore we don't require
 526  * acquire/release semantics here.
 527  *
 528  * Note that it is expected that the pdump "mapping" code will call
 529  * this function multiple times as each page is mapped in turn
 530  *
 531  * Note that NextSymName is the offset from the base of the PMR to the
 532  * next pdump symbolic address (or the end of the PMR if the PMR only
 533  * had one PDUMPMALLOC
 534  */
 535 extern PVRSRV_ERROR
 536 PMR_PDumpSymbolicAddr(const PMR *psPMR,
 537                       IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 538                       IMG_UINT32 ui32NamespaceNameLen,
 539                       IMG_CHAR *pszNamespaceName,
 540                       IMG_UINT32 ui32SymbolicAddrLen,
 541                       IMG_CHAR *pszSymbolicAddr,
 542                       IMG_DEVMEM_OFFSET_T *puiNewOffset,
 543                       IMG_DEVMEM_OFFSET_T *puiNextSymName
 544                       );
 545
 546 /*
 547  * PMRPDumpLoadMemValue32()
 548  *
 549  * writes the current contents of a dword in PMR memory to the pdump
 550  * script stream. Useful for patching a buffer by simply editing the
 551  * script output file in ASCII plain text.
 552  *
 553  */
 554 extern PVRSRV_ERROR
 555 PMRPDumpLoadMemValue32(PMR *psPMR,
 556                                  IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 557                      IMG_UINT32 ui32Value,
 558                      PDUMP_FLAGS_T uiPDumpFlags);
 559
 560 /*
 561  * PMRPDumpLoadMemValue64()
 562  *
 563  * writes the current contents of a dword in PMR memory to the pdump
 564  * script stream. Useful for patching a buffer by simply editing the
 565  * script output file in ASCII plain text.
 566  *
 567  */
 568 extern PVRSRV_ERROR
 569 PMRPDumpLoadMemValue64(PMR *psPMR,
 570                                  IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 571                      IMG_UINT64 ui64Value,
 572                      PDUMP_FLAGS_T uiPDumpFlags);
 573
 574 /*
 575  * PMRPDumpLoadMem()
 576  *
 577  * writes the current contents of the PMR memory to the pdump PRM
 578  * stream, and emits some PDump code to the script stream to LDB said
 579  * bytes from said file. If bZero is IMG_TRUE then the PDump zero page
 580  * is used as the source for the LDB.
 581  *
 582  */
 583 extern PVRSRV_ERROR
 584 PMRPDumpLoadMem(PMR *psPMR,
 585                 IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 586                 IMG_DEVMEM_SIZE_T uiSize,
 587                 PDUMP_FLAGS_T uiPDumpFlags,
 588                 IMG_BOOL bZero);
 589
 590 /*
 591  * PMRPDumpSaveToFile()
 592  *
 593  * emits some PDump that does an SAB (save bytes) using the PDump
 594  * symbolic address of the PMR.  Note that this is generally not the
 595  * preferred way to dump the buffer contents.  There is an equivalent
 596  * function in devicemem_server.h which also emits SAB but using the
 597  * virtual address, which is the "right" way to dump the buffer
 598  * contents to a file.  This function exists just to aid testing by
 599  * providing a means to dump the PMR directly by symbolic address
 600  * also.
 601  */
 602 extern PVRSRV_ERROR
 603 PMRPDumpSaveToFile(const PMR *psPMR,
 604                    IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 605                    IMG_DEVMEM_SIZE_T uiSize,
 606                    IMG_UINT32 uiArraySize,
 607                    const IMG_CHAR *pszFilename);
 608 #else   /* PDUMP */
 609
 610
 611 #ifdef INLINE_IS_PRAGMA
 612 #pragma inline(PMR_PDumpSymbolicAddr)
 613 #endif
 614 static INLINE PVRSRV_ERROR
 615 PMR_PDumpSymbolicAddr(const PMR *psPMR,
 616                       IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 617                       IMG_UINT32 ui32NamespaceNameLen,
 618                       IMG_CHAR *pszNamespaceName,
 619                       IMG_UINT32 ui32SymbolicAddrLen,
 620                       IMG_CHAR *pszSymbolicAddr,
 621                       IMG_DEVMEM_OFFSET_T *puiNewOffset,
 622                       IMG_DEVMEM_OFFSET_T *puiNextSymName)
 623 {
 624         PVR_UNREFERENCED_PARAMETER(psPMR);
 625         PVR_UNREFERENCED_PARAMETER(uiLogicalOffset);
 626         PVR_UNREFERENCED_PARAMETER(ui32NamespaceNameLen);
 627         PVR_UNREFERENCED_PARAMETER(pszNamespaceName);
 628         PVR_UNREFERENCED_PARAMETER(ui32SymbolicAddrLen);
 629         PVR_UNREFERENCED_PARAMETER(pszSymbolicAddr);
 630         PVR_UNREFERENCED_PARAMETER(puiNewOffset);
 631         PVR_UNREFERENCED_PARAMETER(puiNextSymName);
 632         return PVRSRV_OK;
 633 }
 634
 635 #ifdef INLINE_IS_PRAGMA
 636 #pragma inline(PMRPDumpLoadMemValue)
 637 #endif
 638 static INLINE PVRSRV_ERROR
 639 PMRPDumpLoadMemValue32(PMR *psPMR,
 640                                  IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 641                      IMG_UINT32 ui32Value,
 642                      PDUMP_FLAGS_T uiPDumpFlags)
 643 {
 644         PVR_UNREFERENCED_PARAMETER(psPMR);
 645         PVR_UNREFERENCED_PARAMETER(uiLogicalOffset);
 646         PVR_UNREFERENCED_PARAMETER(ui32Value);
 647         PVR_UNREFERENCED_PARAMETER(uiPDumpFlags);
 648         return PVRSRV_OK;
 649 }
 650
 651 #ifdef INLINE_IS_PRAGMA
 652 #pragma inline(PMRPDumpLoadMemValue)
 653 #endif
 654 static INLINE PVRSRV_ERROR
 655 PMRPDumpLoadMemValue64(PMR *psPMR,
 656                                  IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 657                      IMG_UINT64 ui64Value,
 658                      PDUMP_FLAGS_T uiPDumpFlags)
 659 {
 660         PVR_UNREFERENCED_PARAMETER(psPMR);
 661         PVR_UNREFERENCED_PARAMETER(uiLogicalOffset);
 662         PVR_UNREFERENCED_PARAMETER(ui64Value);
 663         PVR_UNREFERENCED_PARAMETER(uiPDumpFlags);
 664         return PVRSRV_OK;
 665 }
 666
 667 #ifdef INLINE_IS_PRAGMA
 668 #pragma inline(PMRPDumpLoadMem)
 669 #endif
 670 static INLINE PVRSRV_ERROR
 671 PMRPDumpLoadMem(PMR *psPMR,
 672                 IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 673                 IMG_DEVMEM_SIZE_T uiSize,
 674                 PDUMP_FLAGS_T uiPDumpFlags,
 675                 IMG_BOOL bZero)
 676 {
 677         PVR_UNREFERENCED_PARAMETER(psPMR);
 678         PVR_UNREFERENCED_PARAMETER(uiLogicalOffset);
 679         PVR_UNREFERENCED_PARAMETER(uiSize);
 680         PVR_UNREFERENCED_PARAMETER(uiPDumpFlags);
 681         PVR_UNREFERENCED_PARAMETER(bZero);
 682         return PVRSRV_OK;
 683 }
 684
 685
 686 #ifdef INLINE_IS_PRAGMA
 687 #pragma inline(PMRPDumpSaveToFile)
 688 #endif
 689 static INLINE PVRSRV_ERROR
 690 PMRPDumpSaveToFile(const PMR *psPMR,
 691                    IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 692                    IMG_DEVMEM_SIZE_T uiSize,
 693                    IMG_UINT32 uiArraySize,
 694                    const IMG_CHAR *pszFilename)
 695 {
 696         PVR_UNREFERENCED_PARAMETER(psPMR);
 697         PVR_UNREFERENCED_PARAMETER(uiLogicalOffset);
 698         PVR_UNREFERENCED_PARAMETER(uiSize);
 699         PVR_UNREFERENCED_PARAMETER(uiArraySize);
 700         PVR_UNREFERENCED_PARAMETER(pszFilename);
 701         return PVRSRV_OK;
 702 }
 703
 704 #endif  /* PDUMP */
 705
 706 /* This function returns the private data that a pmr subtype
 707    squirrelled in here. We use the function table pointer as
 708    "authorization" that this function is being called by the pmr
 709    subtype implementation.  We can assume (assert) that.  It would be
 710    a bug in the implementation of the pmr subtype if this assertion
 711    ever fails. */
 712 extern IMG_VOID *
 713 PMRGetPrivateDataHack(const PMR *psPMR,
 714                       const PMR_IMPL_FUNCTAB *psFuncTab);
 715
 716 extern PVRSRV_ERROR
 717 PMRZeroingPMR(PMR *psPMR,
 718                                 IMG_DEVMEM_LOG2ALIGN_T uiLog2PageSize);
 719
 720 PVRSRV_ERROR
 721 PMRDumpPageList(PMR *psReferencePMR,
 722                                         IMG_DEVMEM_LOG2ALIGN_T uiLog2PageSize);
 723
 724 extern PVRSRV_ERROR
 725 PMRWritePMPageList(/* Target PMR, offset, and length */
 726                    PMR *psPageListPMR,
 727                    IMG_DEVMEM_OFFSET_T uiTableOffset,
 728                    IMG_DEVMEM_SIZE_T  uiTableLength,
 729                    /* Referenced PMR, and "page" granularity */
 730                    PMR *psReferencePMR,
 731                    IMG_DEVMEM_LOG2ALIGN_T uiLog2PageSize,
 732                    PMR_PAGELIST **ppsPageList,
 733                    IMG_UINT64 *pui64CheckSum);
 734
 735 /* Doesn't actually erase the page list - just releases the appropriate refcounts */
 736 extern PVRSRV_ERROR // should be IMG_VOID, surely
 737 PMRUnwritePMPageList(PMR_PAGELIST *psPageList);
 738
 739 #if defined(PDUMP)
 740 extern PVRSRV_ERROR
 741 PMRPDumpPol32(const PMR *psPMR,
 742               IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 743               IMG_UINT32 ui32Value,
 744               IMG_UINT32 ui32Mask,
 745               PDUMP_POLL_OPERATOR eOperator,
 746               PDUMP_FLAGS_T uiFlags);
 747
 748 extern PVRSRV_ERROR
 749 PMRPDumpCBP(const PMR *psPMR,
 750             IMG_DEVMEM_OFFSET_T uiReadOffset,
 751             IMG_DEVMEM_OFFSET_T uiWriteOffset,
 752             IMG_DEVMEM_SIZE_T uiPacketSize,
 753             IMG_DEVMEM_SIZE_T uiBufferSize);
 754 #else
 755
 756 #ifdef INLINE_IS_PRAGMA
 757 #pragma inline(PMRPDumpPol32)
 758 #endif
 759 static INLINE PVRSRV_ERROR
 760 PMRPDumpPol32(const PMR *psPMR,
 761               IMG_DEVMEM_OFFSET_T uiLogicalOffset,
 762               IMG_UINT32 ui32Value,
 763               IMG_UINT32 ui32Mask,
 764               PDUMP_POLL_OPERATOR eOperator,
 765               PDUMP_FLAGS_T uiFlags)
 766 {
 767         PVR_UNREFERENCED_PARAMETER(psPMR);
 768         PVR_UNREFERENCED_PARAMETER(uiLogicalOffset);
 769         PVR_UNREFERENCED_PARAMETER(ui32Value);
 770         PVR_UNREFERENCED_PARAMETER(ui32Mask);
 771         PVR_UNREFERENCED_PARAMETER(eOperator);
 772         PVR_UNREFERENCED_PARAMETER(uiFlags);
 773         return PVRSRV_OK;
 774 }
 775
 776 #ifdef INLINE_IS_PRAGMA
 777 #pragma inline(PMRPDumpCBP)
 778 #endif
 779 static INLINE PVRSRV_ERROR
 780 PMRPDumpCBP(const PMR *psPMR,
 781             IMG_DEVMEM_OFFSET_T uiReadOffset,
 782             IMG_DEVMEM_OFFSET_T uiWriteOffset,
 783             IMG_DEVMEM_SIZE_T uiPacketSize,
 784             IMG_DEVMEM_SIZE_T uiBufferSize)
 785 {
 786         PVR_UNREFERENCED_PARAMETER(psPMR);
 787         PVR_UNREFERENCED_PARAMETER(uiReadOffset);
 788         PVR_UNREFERENCED_PARAMETER(uiWriteOffset);
 789         PVR_UNREFERENCED_PARAMETER(uiPacketSize);
 790         PVR_UNREFERENCED_PARAMETER(uiBufferSize);
 791         return PVRSRV_OK;
 792 }
 793 #endif
 794 /*
 795  * PMRInit()
 796  *
 797  * To be called once and only once to initialise the internal data in
 798  * the PMR module (mutexes and such)
 799  *
 800  * Not for general use.  Only PVRSRVInit(); should be calling this.
 801  */
 802 extern PVRSRV_ERROR
 803 PMRInit(IMG_VOID);
 804
 805 /*
 806  * PMRDeInit()
 807  *
 808  * To be called once and only once to deinitialise the internal data in
 809  * the PMR module (mutexes and such) and for debug checks
 810  *
 811  * Not for general use.  Only PVRSRVDeInit(); should be calling this.
 812  */
 813 extern PVRSRV_ERROR
 814 PMRDeInit(IMG_VOID);
 815
 816 #if defined(PVR_RI_DEBUG)
 817 extern PVRSRV_ERROR
 818 PMRStoreRIHandle(PMR *psPMR,
 819                                  IMG_PVOID hRIHandle);
 820 #endif
 821
 822 #endif /* #ifdef _SRVSRV_PMR_H_ */
 823