dc_client.h 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621
  1. /*************************************************************************/ /*!
  2. @File
  3. @Title Device class interface
  4. @Description Client interface to Display Class devices which have been
  5. registered with services.
  6. @Copyright Copyright (c) Imagination Technologies Ltd. All Rights Reserved
  7. @License Strictly Confidential.
  8. */ /**************************************************************************/
  9. #ifndef DC_CLIENT_H
  10. #define DC_CLIENT_H
  11. #if defined(SUPPORT_DISPLAY_CLASS) || defined(DOXYGEN)
  12. #if defined (__cplusplus)
  13. extern "C" {
  14. #endif
  15. #include "img_types.h"
  16. #include "img_defs.h"
  17. #include "pvrsrv_error.h"
  18. #include "services.h" /* For PVRSRV_DEV_CONNECTION */
  19. #include "pvrsrv_surface.h"
  20. #include "dc_external.h"
  21. #include "pvrsrv_devmem.h" /* Required for PVRSRV_MEMDESC */
  22. /*************************************************************************/ /*!
  23. @Function PVRSRVDCDevicesQueryCount
  24. @Description Query services for the number of registered DC devices.
  25. @Input psConnection Services connection
  26. @Output pui32Count Number of display drivers
  27. @Return PVRSRV_OK if the query was successful
  28. */ /**************************************************************************/
  29. IMG_EXPORT PVRSRV_ERROR PVRSRVDCDevicesQueryCount(const PVRSRV_DEV_CONNECTION *psConnection,
  30. IMG_UINT32 *pui32Count);
  31. /*************************************************************************/ /*!
  32. @Function PVRSRVDCDevicesEnumerate
  33. @Description Query services for the number of registered DC devices and
  34. return their indices in an array.
  35. @Input psConnection Services connection
  36. @Input ui32DeviceArraySize Array size of paui32DeviceIndex
  37. @Output pui32DeviceCount Number of returned devices
  38. @Output paui32DeviceIndex Array of device indices
  39. @Return PVRSRV_OK if the enumeration was successful
  40. */ /**************************************************************************/
  41. IMG_EXPORT PVRSRV_ERROR PVRSRVDCDevicesEnumerate(const PVRSRV_DEV_CONNECTION *psConnection,
  42. IMG_UINT32 ui32DeviceArraySize,
  43. IMG_UINT32 *pui32DeviceCount,
  44. IMG_UINT32 *paui32DeviceIndex);
  45. /*************************************************************************/ /*!
  46. @Function PVRSRVDCDeviceAcquire
  47. @Description Acquire a DC device based on its device index.
  48. A valid index can be acquired with PVRSRVDCDevicesEnumerate.
  49. @Input psConnection Services connection
  50. @Input ui32DeviceIndex DC device index to acquire
  51. @Output phDevice Handle to 3rd party display class device
  52. @Return PVRSRV_OK if the acquire was successful
  53. */ /**************************************************************************/
  54. IMG_EXPORT PVRSRV_ERROR PVRSRVDCDeviceAcquire(const PVRSRV_DEV_CONNECTION *psConnection,
  55. IMG_UINT32 ui32DeviceIndex,
  56. IMG_HANDLE *phDevice);
  57. /*************************************************************************/ /*!
  58. @Function PVRSRVDCDeviceRelease
  59. @Description Release a DC device.
  60. @Input psConnection Services connection
  61. @Input hDevice Handle to 3rd party display class device
  62. */ /**************************************************************************/
  63. IMG_EXPORT void PVRSRVDCDeviceRelease(const PVRSRV_DEV_CONNECTION *psConnection,
  64. IMG_HANDLE hDevice);
  65. /*************************************************************************/ /*!
  66. @Function PVRSRVDCGetInfo
  67. @Description Gets a DC device's info structure.
  68. See #GetInfo()
  69. @Input psConnection Services connection
  70. @Input hDevice Handle to 3rd party display class device
  71. @Output psDisplayInfo Display info
  72. */ /**************************************************************************/
  73. IMG_EXPORT PVRSRV_ERROR PVRSRVDCGetInfo(const PVRSRV_DEV_CONNECTION *psConnection,
  74. IMG_HANDLE hDevice,
  75. DC_DISPLAY_INFO *psDisplayInfo);
  76. /*************************************************************************/ /*!
  77. @Function PVRSRVDCPanelQueryCount
  78. @Description Query the DC for how many panels are connected to it.
  79. See #PanelQueryCount()
  80. @Input psConnection Services connection
  81. @Input hDevice 3rd party display class device
  82. @Output pui32NumPanels Number of panels
  83. @Return PVRSRV_OK if the query was successful
  84. */ /**************************************************************************/
  85. IMG_EXPORT PVRSRV_ERROR PVRSRVDCPanelQueryCount(const PVRSRV_DEV_CONNECTION *psConnection,
  86. IMG_HANDLE hDevice,
  87. IMG_UINT32 *pui32NumPanels);
  88. /*************************************************************************/ /*!
  89. @Function PVRSRVDCPanelQuery
  90. @Description Query the DC for information on what panel(s) are connected
  91. to it and their properties.
  92. See #PanelQuery()
  93. @Input psConnection Services connection
  94. @Input hDevice 3rd party display class device
  95. @Input ui32PanelsArraySize Size of the format and dimension
  96. array size (i.e. number of panels
  97. that can be returned)
  98. @Output pui32NumPanels Number of panels returned
  99. @Output pasPanelInfo Array of panel infos
  100. @Return PVRSRV_OK if the query was successful
  101. */ /**************************************************************************/
  102. IMG_EXPORT PVRSRV_ERROR PVRSRVDCPanelQuery(const PVRSRV_DEV_CONNECTION *psConnection,
  103. IMG_HANDLE hDevice,
  104. IMG_UINT32 ui32PanelsArraySize,
  105. IMG_UINT32 *pui32NumPanels,
  106. PVRSRV_PANEL_INFO *pasPanelInfo);
  107. /*************************************************************************/ /*!
  108. @Function PVRSRVDCFormatQuery
  109. @Description Query the DC to see if it supports the specified format(s).
  110. See #FormatQuery()
  111. @Input psConnection Services connection
  112. @Input hDevice 3rd party display class device
  113. @Input ui32NumFormats Number of formats to check
  114. @Input pasFormat Array of formats to check
  115. @Output pui32Supported For each format, the number of display
  116. pipes that support that format
  117. @Return PVRSRV_OK if the query was successful
  118. */ /**************************************************************************/
  119. IMG_EXPORT PVRSRV_ERROR PVRSRVDCFormatQuery(const PVRSRV_DEV_CONNECTION *psConnection,
  120. IMG_HANDLE hDevice,
  121. IMG_UINT32 ui32NumFormats,
  122. PVRSRV_SURFACE_FORMAT *pasFormat,
  123. IMG_UINT32 *pui32Supported);
  124. /*************************************************************************/ /*!
  125. @Function PVRSRVDCDimQuery
  126. See #DimQuery()
  127. @Description Query the specified display plane for the display dimensions
  128. it supports.
  129. @Input psConnection Services connection
  130. @Input hDevice 3rd party display class device
  131. @Input ui32NumDims Number of dimensions to check
  132. @Input pasDim Array of dimensions to check
  133. @Output pui32Supported For each dimension, the number of
  134. display pipes that support that
  135. dimension
  136. @Return PVRSRV_OK if the query was successful
  137. */ /**************************************************************************/
  138. IMG_EXPORT PVRSRV_ERROR PVRSRVDCDimQuery(const PVRSRV_DEV_CONNECTION *psConnection,
  139. IMG_HANDLE hDevice,
  140. IMG_UINT32 ui32NumDims,
  141. PVRSRV_SURFACE_DIMS *pasDim,
  142. IMG_UINT32 *pui32Supported);
  143. /*************************************************************************/ /*!
  144. @Function PVRSRVDCSetBlank
  145. See #SetBlank()
  146. @Description Enable/disable blanking of the screen
  147. @Input psConnection Services connection
  148. @Input hDevice 3rd party display class device
  149. @Input bEnable Enable/Disable the blanking
  150. @Return PVRSRV_OK on success
  151. */ /**************************************************************************/
  152. IMG_EXPORT PVRSRV_ERROR PVRSRVDCSetBlank(const PVRSRV_DEV_CONNECTION *psConnection,
  153. IMG_HANDLE hDevice,
  154. IMG_BOOL bEnable);
  155. /*************************************************************************/ /*!
  156. @Function PVRSRVDCSetVSyncReporting
  157. See #SetVSyncReporting()
  158. @Description Enable VSync reporting on every vsync.
  159. The DC device will be asked to notify services with
  160. a PVRSRVCheckStatus() call whenever a vsync event occurred.
  161. PVRSRVCheckStatus will signal the global event object to wake
  162. up the driver and the GPU to schedule unblocked work.
  163. @Input psConnection Services connection
  164. @Input hDevice 3rd party display class device
  165. @Input bEnable Enable/Disable the reporting
  166. @Return PVRSRV_OK on success
  167. */ /**************************************************************************/
  168. IMG_EXPORT PVRSRV_ERROR PVRSRVDCSetVSyncReporting(const PVRSRV_DEV_CONNECTION *psConnection,
  169. IMG_HANDLE hDevice,
  170. IMG_BOOL bEnable);
  171. /*************************************************************************/ /*!
  172. @Function PVRSRVDCLastVSyncQuery
  173. @Description Query the time the last vsync happened.
  174. See #LastVSyncQuery()
  175. @Input psConnection Services connection
  176. @Input hDevice 3rd party display class device
  177. @Output pi64Timestamp The requested timestamp in ns
  178. @Return PVRSRV_OK if the query was successful
  179. */ /**************************************************************************/
  180. IMG_EXPORT PVRSRV_ERROR PVRSRVDCLastVSyncQuery(const PVRSRV_DEV_CONNECTION *psConnection,
  181. IMG_HANDLE hDevice,
  182. IMG_INT64 *pi64Timestamp);
  183. /*************************************************************************/ /*!
  184. @Function DCDisplayContextCreate
  185. @Description Create display context. Display reconfigurations are done on a
  186. display context and guaranteed to happen in order and when
  187. any dependencies have been meet.
  188. There is no connection between a display pipe or panel and a
  189. display context (i.e. a display context might control more than
  190. one display plane, and the number of display planes that
  191. are modified per reconfiguration can vary).
  192. A display context can be seen as a
  193. container in which buffers are allocated or imported and
  194. reconfigurations are made. It's purely a SW concept and is
  195. there to ensure that operations issued on the same display
  196. context are issued in order.
  197. See #ContextCreate()
  198. @Input psConnection Services connection
  199. @Input hDevice 3rd party display class device
  200. @Output phDisplayContext Created display context
  201. @Return PVRSRV_OK if the context was created
  202. */ /**************************************************************************/
  203. IMG_EXPORT PVRSRV_ERROR PVRSRVDCDisplayContextCreate(PVRSRV_DEV_CONNECTION *psConnection,
  204. IMG_HANDLE hDevice,
  205. IMG_HANDLE *phDisplayContext);
  206. /*************************************************************************/ /*!
  207. @Function PVRSRVDCContextConfigureCheck
  208. @Description Check a configuration of the specified display context is
  209. valid. The arrays should be z-sorted, with the farthest plane
  210. first and the nearest plane last.
  211. See #ContextConfigureCheck()
  212. @Input psConnection Services connection
  213. @Input hDisplayContext Display context
  214. @Input ui32PipeCount Number of display pipes to configure
  215. @Input pasConfigInfo Array of surface attributes (one for
  216. each display plane)
  217. @Input ahBuffers Array of buffers (one for
  218. each display plane)
  219. @Return PVRSRV_OK if the reconfiguration was valid
  220. */ /**************************************************************************/
  221. IMG_EXPORT PVRSRV_ERROR PVRSRVDCContextConfigureCheck(const PVRSRV_DEV_CONNECTION *psConnection,
  222. IMG_HANDLE hDisplayContext,
  223. IMG_UINT32 ui32PipeCount,
  224. PVRSRV_SURFACE_CONFIG_INFO *pasConfigInfo,
  225. IMG_HANDLE *ahBuffers);
  226. /*************************************************************************/ /*!
  227. @Function PVRSRVDCContextConfigureWithFence
  228. @Description Queue a configuration of the display pipeline to happen on
  229. the specified display context. The arrays should be z-sorted,
  230. with the farthest plane first and the nearest plane last.
  231. Makes use OS native syncs instead of Services sync prims.
  232. See #ContextConfigure()
  233. @Input psConnection Services connection
  234. @Input hDisplayContext Display context
  235. @Input ui32PipeCount Number of display pipes to configure
  236. @Input pasConfigInfo Array of surface attributes (one for
  237. each display plane)
  238. @Input ahBuffers Array of buffers (one for
  239. each display plane)
  240. @Input ui32DisplayPeriod The number of VSync periods this
  241. configuration should be displayed for
  242. @Input ui32MaxDepth If non-zero, block until fewer than
  243. this number of reconfigure requests
  244. are outstanding
  245. @Input i32AcquireFenceFd fd of fence to wait for before executing
  246. @Output pi32ReleaseFenceFd fd of fence to signal when call has been
  247. executed
  248. @Return PVRSRV_OK if the reconfiguration was successfully queued
  249. */ /**************************************************************************/
  250. IMG_EXPORT PVRSRV_ERROR PVRSRVDCContextConfigureWithFence(const PVRSRV_DEV_CONNECTION *psConnection,
  251. IMG_HANDLE hDisplayContext,
  252. IMG_UINT32 ui32PipeCount,
  253. PVRSRV_SURFACE_CONFIG_INFO *pasConfigInfo,
  254. IMG_HANDLE *ahBuffers,
  255. IMG_UINT32 ui32DisplayPeriod,
  256. IMG_UINT32 ui32MaxDepth,
  257. IMG_INT32 i32AcquireFenceFd,
  258. IMG_INT32 *pi32ReleaseFenceFd);
  259. /*************************************************************************/ /*!
  260. @Function DCDisplayContextDestroy
  261. @Description Destroy a display context.
  262. See #ContextDestroy()
  263. @Input psConnection Services connection
  264. @Input hDisplayContext Display context to destroy
  265. @Return PVRSRV_OK if the context was created
  266. */ /**************************************************************************/
  267. IMG_EXPORT PVRSRV_ERROR PVRSRVDCDisplayContextDestroy(PVRSRV_DEV_CONNECTION *psConnection,
  268. IMG_HANDLE hDisplayContext);
  269. /*************************************************************************/ /*!
  270. @Function PVRSRVDCBufferAlloc
  271. @Description Allocate a display buffer.
  272. The call requests the buffer from the 3rd party display class.
  273. See #BufferAlloc()
  274. @Input psConnection Services connection
  275. @Input hDisplayContext Display context this buffer will be
  276. used on
  277. @Input psSurfInfo Attributes of the buffer
  278. @Output pui32ByteStride Stride of the allocated surface
  279. @Output phBuffer Handle to allocated buffer
  280. @Return PVRSRV_OK if the buffer was successfully allocated
  281. */ /**************************************************************************/
  282. IMG_EXPORT PVRSRV_ERROR PVRSRVDCBufferAlloc(const PVRSRV_DEV_CONNECTION *psConnection,
  283. IMG_HANDLE hDisplayContext,
  284. PVRSRV_SURFACE_INFO *psSurfInfo,
  285. IMG_UINT32 *pui32ByteStride,
  286. IMG_HANDLE *phBuffer);
  287. /*************************************************************************/ /*!
  288. @Function PVRSRVDCBufferFree
  289. @Description Free a display buffer allocated with PVRSRVDCBufferAlloc
  290. See #BufferFree()
  291. @Input psConnection Services connection
  292. @Input hBuffer Handle to buffer to free
  293. @Return PVRSRV_OK if the buffer was successfully allocated
  294. */ /**************************************************************************/
  295. IMG_EXPORT PVRSRV_ERROR PVRSRVDCBufferFree(const PVRSRV_DEV_CONNECTION *psConnection,
  296. IMG_HANDLE hBuffer);
  297. /*************************************************************************/ /*!
  298. @Function PVRSRVDCBufferImport
  299. @Description Import Services device memory in form of services MemDescs into
  300. the display driver.
  301. See #BufferImport()
  302. @Input psConnection Services connection
  303. @Input hDisplayContext Display context this buffer will be
  304. used on
  305. @Input pasMemDesc Array of MemDescs to import (one per
  306. colour channel)
  307. @Input psImportInfo Attributes of the import buffer
  308. @Output phBuffer Handle to imported buffer
  309. @Return PVRSRV_OK if the buffer was successfully imported
  310. */ /**************************************************************************/
  311. IMG_EXPORT PVRSRV_ERROR PVRSRVDCBufferImport(const PVRSRV_DEV_CONNECTION *psConnection,
  312. IMG_HANDLE hDisplayContext,
  313. PVRSRV_MEMDESC *pasMemDesc,
  314. DC_BUFFER_IMPORT_INFO *psImportInfo,
  315. IMG_HANDLE *phBuffer);
  316. /*************************************************************************/ /*!
  317. @Function PVRSRVDCBufferUnimport
  318. @Description Unimport a buffer
  319. @Input psConnection Services connection
  320. @Input hBuffer Buffer to unimport
  321. */ /**************************************************************************/
  322. IMG_EXPORT void PVRSRVDCBufferUnimport(const PVRSRV_DEV_CONNECTION *psConnection,
  323. IMG_HANDLE hBuffer);
  324. /*************************************************************************/ /*!
  325. @Function PVRSRVDCSystemBufferAcquire
  326. @Description DEPRECATED, please use PVRSRVDCBufferAlloc
  327. Acquire the system buffer from the 3rd party display class.
  328. This is usually a buffer that has been created by the OS via a
  329. native interface compared to a buffer that was created on demand
  330. by the display driver. Can be used for direct frame buffer
  331. rendering.
  332. See #BufferSystemAcquire()
  333. @Input psConnection Services connection
  334. @Input hDevice 3rd party display class device
  335. @Output pui32ByteStride Stride of the buffer in Byte
  336. @Output phBuffer Buffer handle
  337. @Return PVRSRV_OK if the query was successful
  338. */ /**************************************************************************/
  339. IMG_EXPORT PVRSRV_ERROR PVRSRVDCSystemBufferAcquire(const PVRSRV_DEV_CONNECTION *psConnection,
  340. IMG_HANDLE hDevice,
  341. IMG_UINT32 *pui32ByteStride,
  342. IMG_HANDLE *phBuffer);
  343. /*************************************************************************/ /*!
  344. @Function PVRSRVDCSystemBufferRelease
  345. @Description DEPRECATED, please use PVRSRVDCBufferFree
  346. Release the system buffer
  347. See #BufferSystemRelease()
  348. @Input psConnection Services connection
  349. @Input hBuffer Buffer handle
  350. @Return PVRSRV_OK if the release was successful
  351. */ /**************************************************************************/
  352. IMG_EXPORT PVRSRV_ERROR PVRSRVDCSystemBufferRelease(const PVRSRV_DEV_CONNECTION *psConnection,
  353. IMG_HANDLE hBuffer);
  354. /*************************************************************************/ /*!
  355. @Function PVRSRVDCBufferPin
  356. @Description Maps the buffer into the display controller if it hasn't already
  357. been mapped and make sure it won't get unmapped until
  358. PVRSRVDCBufferUnpin is called.
  359. Note: Without calling this the display controller will still
  360. be asked to map the buffer when that buffer is specified
  361. in a call to PVRSRVDCContextConfigure and will be asked to
  362. unmap the buffer once the configuration has been retired.
  363. This function is provided to allow the client to have control
  364. over when the display driver maps and unmaps surfaces because
  365. the application often knows better when it is most efficient
  366. to do the mapping.
  367. See #BufferMap()
  368. @Input psConnection Services connection
  369. @Input hBuffer Buffer we're pinning
  370. @Output phPinHandle Pin handle
  371. @Return PVRSRV_OK if the buffer was successfully pinned
  372. */ /**************************************************************************/
  373. IMG_EXPORT PVRSRV_ERROR PVRSRVDCBufferPin(const PVRSRV_DEV_CONNECTION *psConnection,
  374. IMG_HANDLE hBuffer,
  375. IMG_HANDLE *phPinHandle);
  376. /*************************************************************************/ /*!
  377. @Function PVRSRVDCBufferUnpin
  378. @Description Unpin the buffer and potentially unmap it from the display
  379. controller.
  380. Note: It is safe to call this with queued operations on
  381. the buffer due to the fact that PVRSRVDCContextConfigure will
  382. have already taken a mapping reference and so the buffer
  383. won't actually be unmapped until the configuration that is using
  384. the buffer has been retired.
  385. See #BufferUnmap()
  386. @Input psConnection Services connection
  387. @Input hPinHandle Pin handle we're releasing
  388. */ /**************************************************************************/
  389. IMG_EXPORT void PVRSRVDCBufferUnpin(const PVRSRV_DEV_CONNECTION *psConnection,
  390. IMG_HANDLE hPinHandle);
  391. /*************************************************************************/ /*!
  392. @Function PVRSRVDCBufferAcquire
  393. @Description Acquire a handle from the buffer which the device memory manager
  394. can use to turn into a MEMDESC. The buffer could come from
  395. either PVRSRVDCBufferAlloc or PVRSRVDCSystemBufferAcquire.
  396. Clients can make it available to services via
  397. PVRSRVDevmemLocalImport which returns a MEMDESC.
  398. @Input psConnection Services connection
  399. @Input hBuffer Buffer we're acquiring
  400. @Output phExtMem External memory handle
  401. @Return PVRSRV_OK if the buffer was successfully acquired
  402. */ /**************************************************************************/
  403. IMG_EXPORT PVRSRV_ERROR PVRSRVDCBufferAcquire(const PVRSRV_DEV_CONNECTION *psConnection,
  404. IMG_HANDLE hBuffer,
  405. IMG_HANDLE *phExtMem);
  406. /*************************************************************************/ /*!
  407. @Function PVRSRVDCBufferRelease
  408. @Description Release the buffers device memory manager handle
  409. @Input psConnection Services connection
  410. @Input hExtMem External memory handle
  411. */ /**************************************************************************/
  412. IMG_EXPORT void PVRSRVDCBufferRelease(const PVRSRV_DEV_CONNECTION *psConnection,
  413. IMG_HANDLE hExtMem);
  414. /*************************************************************************/ /*!
  415. @Function PVRSRVDCGetDisplayContextServerHandle
  416. @Description Fetches the server-side display context handle.
  417. @Input hDisplayContextClient Client-side display context handle
  418. @Return Server-side display context handle
  419. */ /**************************************************************************/
  420. IMG_EXPORT IMG_HANDLE PVRSRVDCGetDisplayContextServerHandle(IMG_HANDLE hDisplayContextClient);
  421. #if defined (__cplusplus)
  422. }
  423. #endif
  424. #endif /* defined(SUPPORT_DISPLAY_CLASS) */
  425. #endif /*DC_CLIENT_H*/