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 30 #ifndef _vg_lite_hal_h_ 31 #define _vg_lite_hal_h_ 32 33 #include "vg_lite_platform.h" 34 #include "vg_lite_os.h" 35 #include "vg_lite_kernel.h" 36 37 #define VGLITE_MEM_ALIGNMENT 128 38 #define THREAD_LENGTH 8 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /*! 45 @brief Wait a number of milliseconds. 46 47 @discussion 48 The VGLite hardware requires some waiting when changing clock frequencies or issuing a reset. This is the wrapper function 49 for the delay function. 50 51 @param milliseconds 52 The number of milliseconds to wait. 53 */ 54 void vg_lite_hal_delay(uint32_t milliseconds); 55 56 /*! 57 @brief Initialize the hardware. 58 59 @discussion 60 The VGLite kernel knows how to program its own hardware, but in any SOC there might be additional control required for 61 turning on the power or initializing the clocks. This function gets called by the VGLite kernel before the VGLite graphics 62 hardware gets initialized by the VGLite kernel itself and allows for SOC power management control. 63 64 The implementer should make sure that on exit of this function the power and clock to the VGLite graphics hardware is 65 turned on and stable. 66 */ 67 vg_lite_error_t vg_lite_hal_initialize(void); 68 69 /*! 70 @brief Uninitialize the hardware. 71 72 @discussion 73 The VGLite kernel knows how to program its own hardware, but in any SOC there might be additional control required for 74 turning off the power or uninitializing the clocks. This function gets called by the VGLite kernel after the VGLite 75 graphics hardware gets uninitialized by the VGLite kernel itself and allows for SOC power management control. 76 77 On exit of this function it is okay to have the power and/or clock to the VGLite graphics hardware turned off. 78 */ 79 void vg_lite_hal_deinitialize(void); 80 81 /*! 82 @brief Allocate contiguous video memory. 83 84 @discussion 85 Any memory the VGLite graphics hardware will see should be allocated as contiguous memory. Any allocated memory will be 86 addressed through an opaque handle, usually a pointer to an opaque structure. The porting layer can put any information it 87 needs inside this structure. 88 89 @param size 90 The number of bytes to allocate. 91 92 @param logical 93 A pointer to a variable that will receive the logical address of the allocated memory for the CPU. 94 95 @param gpu 96 A pointer to a variable that will receive the physical address of the allocated memory for the VGLite graphics hardware. 97 98 @result 99 A pointer to an opaque structure that will be used as the memory handle. <code>NULL</code> should be returned if there is not 100 enough memory. 101 */ 102 vg_lite_error_t vg_lite_hal_allocate_contiguous(unsigned long size, void ** logical, uint32_t * physical,void ** node); 103 104 /*! 105 @brief Free contiguous video memory. 106 107 @discussion 108 Free the memory allocated by {@link vg_lite_hal_allocate_contiguous}. After this function returns, the associated memory 109 handle is no longer a valid handle. 110 111 @param memory_handle 112 A pointer to an opaque structure returned by {@link vg_lite_hal_allocate_contiguous}. 113 */ 114 void vg_lite_hal_free_contiguous(void * memory_handle); 115 116 /*! 117 @brief remove unfree node when continuously allocate buffer without free buffer. 118 119 @discussion 120 Free the node allocated by {@link kmalloc}. After this function returns, the associated memory 121 handle is no longer a valid handle. 122 */ 123 void vg_lite_hal_free_os_heap(void); 124 125 /*! 126 @brief Map contiguous logical or physical memory into the VGLite graphics hardware space. 127 128 @discussion 129 Any memory, like a frame buffer or some pre-allocated image or path data, needs to be mapped into the VGLite graphics 130 hardware address space and wrapped by a memory handle. This allows the VGLite graphics hardware access that memory 131 directly. 132 133 Either a logical or a physical address should be passed in to map. 134 135 @param size 136 The number of bytes to map. 137 138 @param logical 139 The logical address of the memory region to map or <code>NULL</code> if the logical address is not known. 140 141 @param physical 142 The physical address of the memory region to map if <code>logical</code> is <code>NULL</code>. 143 144 @param gpu 145 A pointer to a variable that will receive the VGLite graphics hardware addressable address of the mapped region. 146 147 @result 148 A pointer to an opaque structure that will be used as the memory handle. <code>NULL</code> should be returned if there is 149 not enough system resources to map the region. 150 */ 151 void * vg_lite_hal_map(unsigned long size, void * logical, uint32_t physical, uint32_t * gpu); 152 153 /*! 154 @brief Unmap a previously mapped region. 155 156 @discussion 157 If a mapped region by {@link vg_lite_hal_map} is no longer needed, it should be unmapped to free up any allocated system 158 resources used when mapping the region. 159 160 @param memory_handle 161 A pointer to an opaque structure returned by {@link vg_lite_hal_map}. 162 */ 163 void vg_lite_hal_unmap(void * memory_handle); 164 165 /*! 166 @brief Execute a memory barrier. 167 168 @discussion 169 Some systems require a a memory barrier to make sure all store operations in the CPU have been handled. This is the wrapper 170 function for a memory barrier. 171 */ 172 void vg_lite_hal_barrier(void); 173 174 /*! 175 @brief Read data from a register from the VGLite graphics hardware. 176 177 @discussion 178 In order to communicate with the VGLite graphics hardware, the kernel needs to read and write to some hardware registers. 179 In each SOC those registers could be allocated at a different space in the physical memory map. 180 181 @param address 182 The relative address of the VGLite graphics hardware register to read from. 183 184 @result 185 The 32-bit value returned from reading the register. 186 */ 187 uint32_t vg_lite_hal_peek(uint32_t address); 188 189 /*! 190 @brief Write data to a register from the VGLite graphics hardware. 191 192 @discussion 193 In order to communicate with the VGLite graphics hardware, the kernel needs to read and write to some hardware registers. 194 In each SOC those registers could be allocated at a different space in the physical memory map. 195 196 @param address 197 The relative address of the VGLite graphics hardware register to write to. 198 199 @param data 200 The data to write to the VGLite graphics hardware register. 201 */ 202 void vg_lite_hal_poke(uint32_t address, uint32_t data); 203 204 /*! 205 @brief query the remaining allocate contiguous video memory. 206 207 @param data 208 The data to get the remaining allocate contiguous video memory bytes. 209 */ 210 vg_lite_error_t vg_lite_hal_query_mem(vg_lite_kernel_mem_t *mem); 211 212 /*! 213 @brief Wait until an interrupt from the VGLite graphics hardware has been received. 214 215 @discussion 216 Currently, the VGLite API is synchronous. This means that after each call it will wait until the VGLite graphics hardware 217 has completed. The VGLite graphics hardware will send an interrupt when it is finished, and this function will wait until 218 that interrupt has been received by the operating system. 219 220 A timeout value is specified in order if the kernel wants to wait for a specific number of milliseconds fir the interrupt to 221 occur. If the interrupt does not occur in the specified timeout, a timeout error will be returned. 222 223 @param timeout 224 The number of milliseconds to wait for the interrupt before returning a timeout error. If <code>timeout = 0xFFFFFFFF</code> 225 then {@link vg_lite_hal_wait_interrupt} will wait forever for the interrupt. 226 227 @param mask 228 Irq event mask to wait for. 229 230 @result 231 A boolean value indicating whether the interrupt was received (1) or not (0). 232 */ 233 int32_t vg_lite_hal_wait_interrupt(uint32_t timeout, uint32_t mask, uint32_t * value); 234 235 #if !defined(VG_DRIVER_SINGLE_THREAD) 236 /*! 237 @brief Submit the current command buffer to the command queue. 238 239 @param context 240 Address of kernel context. 241 242 @param physical 243 Current command buffer physical address. 244 245 @param offset 246 Current command buffer offset. 247 248 @param size 249 Current command buffer size. 250 251 @param event 252 The async event to use to track the response for this request. 253 */ 254 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); 255 256 /*! 257 @brief Wait for the current command buffer to be executed. 258 259 @param timeout 260 Timeout in milliseconds. 261 262 @param event 263 The async event to wait for. If the event's signal is 1, the current command 264 buffer has been executed. 265 */ 266 vg_lite_error_t vg_lite_hal_wait(uint32_t timeout, vg_lite_os_async_event_t *event); 267 #endif /* not defined(VG_DRIVER_SINGLE_THREAD) */ 268 269 #ifdef __cplusplus 270 } 271 #endif 272 #endif /* _vg_lite_hal_h_ */ 273