vg_lite_hal.h 9.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272
  1. /****************************************************************************
  2. *
  3. * The MIT License (MIT)
  4. *
  5. * Copyright 2012 - 2020 Vivante Corporation, Santa Clara, California.
  6. * All Rights Reserved.
  7. *
  8. * Permission is hereby granted, free of charge, to any person obtaining
  9. * a copy of this software and associated documentation files (the
  10. * 'Software'), to deal in the Software without restriction, including
  11. * without limitation the rights to use, copy, modify, merge, publish,
  12. * distribute, sub license, and/or sell copies of the Software, and to
  13. * permit persons to whom the Software is furnished to do so, subject
  14. * to the following conditions:
  15. *
  16. * The above copyright notice and this permission notice (including the
  17. * next paragraph) shall be included in all copies or substantial
  18. * portions of the Software.
  19. *
  20. * THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
  21. * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  22. * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
  23. * IN NO EVENT SHALL VIVANTE AND/OR ITS SUPPLIERS BE LIABLE FOR ANY
  24. * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  25. * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  26. * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  27. *
  28. *****************************************************************************/
  29. #ifndef _vg_lite_hal_h_
  30. #define _vg_lite_hal_h_
  31. #include "vg_lite_platform.h"
  32. #include "vg_lite_os.h"
  33. #include "vg_lite_kernel.h"
  34. #define VGLITE_MEM_ALIGNMENT 128
  35. #define THREAD_LENGTH 8
  36. #ifdef __cplusplus
  37. extern "C" {
  38. #endif
  39. /*!
  40. @brief Wait a number of milliseconds.
  41. @discussion
  42. The VGLite hardware requires some waiting when changing clock frequencies or issuing a reset. This is the wrapper function
  43. for the delay function.
  44. @param milliseconds
  45. The number of milliseconds to wait.
  46. */
  47. void vg_lite_hal_delay(uint32_t milliseconds);
  48. /*!
  49. @brief Initialize the hardware.
  50. @discussion
  51. The VGLite kernel knows how to program its own hardware, but in any SOC there might be additional control required for
  52. turning on the power or initializing the clocks. This function gets called by the VGLite kernel before the VGLite graphics
  53. hardware gets initialized by the VGLite kernel itself and allows for SOC power management control.
  54. The implementer should make sure that on exit of this function the power and clock to the VGLite graphics hardware is
  55. turned on and stable.
  56. */
  57. vg_lite_error_t vg_lite_hal_initialize(void);
  58. /*!
  59. @brief Uninitialize the hardware.
  60. @discussion
  61. The VGLite kernel knows how to program its own hardware, but in any SOC there might be additional control required for
  62. turning off the power or uninitializing the clocks. This function gets called by the VGLite kernel after the VGLite
  63. graphics hardware gets uninitialized by the VGLite kernel itself and allows for SOC power management control.
  64. On exit of this function it is okay to have the power and/or clock to the VGLite graphics hardware turned off.
  65. */
  66. void vg_lite_hal_deinitialize(void);
  67. /*!
  68. @brief Allocate contiguous video memory.
  69. @discussion
  70. Any memory the VGLite graphics hardware will see should be allocated as contiguous memory. Any allocated memory will be
  71. addressed through an opaque handle, usually a pointer to an opaque structure. The porting layer can put any information it
  72. needs inside this structure.
  73. @param size
  74. The number of bytes to allocate.
  75. @param logical
  76. A pointer to a variable that will receive the logical address of the allocated memory for the CPU.
  77. @param gpu
  78. A pointer to a variable that will receive the physical address of the allocated memory for the VGLite graphics hardware.
  79. @result
  80. A pointer to an opaque structure that will be used as the memory handle. <code>NULL</code> should be returned if there is not
  81. enough memory.
  82. */
  83. vg_lite_error_t vg_lite_hal_allocate_contiguous(unsigned long size, void ** logical, uint32_t * physical,void ** node);
  84. /*!
  85. @brief Free contiguous video memory.
  86. @discussion
  87. Free the memory allocated by {@link vg_lite_hal_allocate_contiguous}. After this function returns, the associated memory
  88. handle is no longer a valid handle.
  89. @param memory_handle
  90. A pointer to an opaque structure returned by {@link vg_lite_hal_allocate_contiguous}.
  91. */
  92. void vg_lite_hal_free_contiguous(void * memory_handle);
  93. /*!
  94. @brief remove unfree node when continuously allocate buffer without free buffer.
  95. @discussion
  96. Free the node allocated by {@link kmalloc}. After this function returns, the associated memory
  97. handle is no longer a valid handle.
  98. */
  99. void vg_lite_hal_free_os_heap(void);
  100. /*!
  101. @brief Map contiguous logical or physical memory into the VGLite graphics hardware space.
  102. @discussion
  103. Any memory, like a frame buffer or some pre-allocated image or path data, needs to be mapped into the VGLite graphics
  104. hardware address space and wrapped by a memory handle. This allows the VGLite graphics hardware access that memory
  105. directly.
  106. Either a logical or a physical address should be passed in to map.
  107. @param size
  108. The number of bytes to map.
  109. @param logical
  110. The logical address of the memory region to map or <code>NULL</code> if the logical address is not known.
  111. @param physical
  112. The physical address of the memory region to map if <code>logical</code> is <code>NULL</code>.
  113. @param gpu
  114. A pointer to a variable that will receive the VGLite graphics hardware addressable address of the mapped region.
  115. @result
  116. A pointer to an opaque structure that will be used as the memory handle. <code>NULL</code> should be returned if there is
  117. not enough system resources to map the region.
  118. */
  119. void * vg_lite_hal_map(unsigned long size, void * logical, uint32_t physical, uint32_t * gpu);
  120. /*!
  121. @brief Unmap a previously mapped region.
  122. @discussion
  123. If a mapped region by {@link vg_lite_hal_map} is no longer needed, it should be unmapped to free up any allocated system
  124. resources used when mapping the region.
  125. @param memory_handle
  126. A pointer to an opaque structure returned by {@link vg_lite_hal_map}.
  127. */
  128. void vg_lite_hal_unmap(void * memory_handle);
  129. /*!
  130. @brief Execute a memory barrier.
  131. @discussion
  132. Some systems require a a memory barrier to make sure all store operations in the CPU have been handled. This is the wrapper
  133. function for a memory barrier.
  134. */
  135. void vg_lite_hal_barrier(void);
  136. /*!
  137. @brief Read data from a register from the VGLite graphics hardware.
  138. @discussion
  139. In order to communicate with the VGLite graphics hardware, the kernel needs to read and write to some hardware registers.
  140. In each SOC those registers could be allocated at a different space in the physical memory map.
  141. @param address
  142. The relative address of the VGLite graphics hardware register to read from.
  143. @result
  144. The 32-bit value returned from reading the register.
  145. */
  146. uint32_t vg_lite_hal_peek(uint32_t address);
  147. /*!
  148. @brief Write data to a register from the VGLite graphics hardware.
  149. @discussion
  150. In order to communicate with the VGLite graphics hardware, the kernel needs to read and write to some hardware registers.
  151. In each SOC those registers could be allocated at a different space in the physical memory map.
  152. @param address
  153. The relative address of the VGLite graphics hardware register to write to.
  154. @param data
  155. The data to write to the VGLite graphics hardware register.
  156. */
  157. void vg_lite_hal_poke(uint32_t address, uint32_t data);
  158. /*!
  159. @brief query the remaining allocate contiguous video memory.
  160. @param data
  161. The data to get the remaining allocate contiguous video memory bytes.
  162. */
  163. vg_lite_error_t vg_lite_hal_query_mem(vg_lite_kernel_mem_t *mem);
  164. /*!
  165. @brief Wait until an interrupt from the VGLite graphics hardware has been received.
  166. @discussion
  167. Currently, the VGLite API is synchronous. This means that after each call it will wait until the VGLite graphics hardware
  168. has completed. The VGLite graphics hardware will send an interrupt when it is finished, and this function will wait until
  169. that interrupt has been received by the operating system.
  170. A timeout value is specified in order if the kernel wants to wait for a specific number of milliseconds fir the interrupt to
  171. occur. If the interrupt does not occur in the specified timeout, a timeout error will be returned.
  172. @param timeout
  173. The number of milliseconds to wait for the interrupt before returning a timeout error. If <code>timeout = 0xFFFFFFFF</code>
  174. then {@link vg_lite_hal_wait_interrupt} will wait forever for the interrupt.
  175. @param mask
  176. Irq event mask to wait for.
  177. @result
  178. A boolean value indicating whether the interrupt was received (1) or not (0).
  179. */
  180. int32_t vg_lite_hal_wait_interrupt(uint32_t timeout, uint32_t mask, uint32_t * value);
  181. #if !defined(VG_DRIVER_SINGLE_THREAD)
  182. /*!
  183. @brief Submit the current command buffer to the command queue.
  184. @param context
  185. Address of kernel context.
  186. @param physical
  187. Current command buffer physical address.
  188. @param offset
  189. Current command buffer offset.
  190. @param size
  191. Current command buffer size.
  192. @param event
  193. The async event to use to track the response for this request.
  194. */
  195. vg_lite_error_t vg_lite_hal_submit(uint32_t context,uint32_t physical, uint32_t offset, uint32_t size, vg_lite_os_async_event_t *event);
  196. /*!
  197. @brief Wait for the current command buffer to be executed.
  198. @param timeout
  199. Timeout in milliseconds.
  200. @param event
  201. The async event to wait for. If the event's signal is 1, the current command
  202. buffer has been executed.
  203. */
  204. vg_lite_error_t vg_lite_hal_wait(uint32_t timeout, vg_lite_os_async_event_t *event);
  205. #endif /* not defined(VG_DRIVER_SINGLE_THREAD) */
  206. #ifdef __cplusplus
  207. }
  208. #endif
  209. #endif /* _vg_lite_hal_h_ */