hal_gfx_hal.h
Go to the documentation of this file.
1 /**
2  ****************************************************************************************
3  *
4  * @file hal_gfx_hal.h
5  * @author BLE Driver Team
6  * @brief Header file containing functions prototypes of Graphics library.
7  *
8  ****************************************************************************************
9  * @attention
10  #####Copyright (c) 2019 GOODIX
11  All rights reserved.
12 
13  Redistribution and use in source and binary forms, with or without
14  modification, are permitted provided that the following conditions are met:
15  * Redistributions of source code must retain the above copyright
16  notice, this list of conditions and the following disclaimer.
17  * Redistributions in binary form must reproduce the above copyright
18  notice, this list of conditions and the following disclaimer in the
19  documentation and/or other materials provided with the distribution.
20  * Neither the name of GOODIX nor the names of its contributors may be used
21  to endorse or promote products derived from this software without
22  specific prior written permission.
23 
24  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27  ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
28  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34  POSSIBILITY OF SUCH DAMAGE.
35  ****************************************************************************************
36  */
37 
38 /** @addtogroup GRAPHICS_SDK Graphics
39  * @{
40  */
41 
42 /** @addtogroup HAL_GFX HAL GFX
43  * @{
44  */
45 
46 /** @defgroup HAL_GFX_HAL GFX HAL
47  * @brief GPU low layer interfaces, adaptation platform MCU.
48  * @{
49  */
50 #ifndef HAL_GFX_HAL_H__
51 #define HAL_GFX_HAL_H__
52 
53 #include "hal_gfx_sys_defs.h"
54 
55 #ifdef __cplusplus
56 extern "C" {
57 #endif
58 
59 /**
60  * @defgroup HAL_GFX_HAL_MACRO Defines
61  * @{
62  */
63 #define MUTEX_RB 0 /**< Mutex for ringbuffer */
64 #define MUTEX_MALLOC 1 /**< Mutex for malloc */
65 #define MUTEX_FLUSH 2 /**< Mutex for flush */
66 #define MUTEX_MAX 2 /**< MAX */
67 /** @} */
68 
69 /**
70  * @defgroup HAL_GFX_HAL_STRUCT Structures
71  * @{
72  */
73 /**@brief The base structure of gpu memory. */
74 typedef struct hal_gfx_buffer_t_
75 {
76  int size; /**< Size of buffer */
77  int fd; /**< File Descriptor of buffer */
78  void *base_virt; /**< Virtual address of buffer */
79  uintptr_t base_phys; /**< Physical address of buffer */
80 } hal_gfx_buffer_t;
81 
82 /**@brief The ringbuffer structure. */
83 typedef struct hal_gfx_ringbuffer_t_
84 {
85  hal_gfx_buffer_t bo; /**< Memory base structure */
86  int offset; /**< Record ringbuffer usage */
87  int last_submission_id; /**< Latest command list id */
88 } hal_gfx_ringbuffer_t;
89 
90 /** @} */
91 
92 /**
93  * @defgroup HAL_GFX_HAL_FUNCTION Functions
94  * @{
95  */
96 /**
97  *****************************************************************************************
98  * @brief Initialize system. Implementor defined. Called in hal_gfx_init()
99  *
100  * @return 0 if no errors occurred
101  *****************************************************************************************
102  */
103 int32_t hal_gfx_sys_init(void);
104 
105 /**
106  *****************************************************************************************
107  * @brief Wait for interrupt from the GPU
108  *
109  * @return 0 on success
110  *****************************************************************************************
111  */
112 int hal_gfx_wait_irq(void);
113 
114 /**
115  *****************************************************************************************
116  * @brief Wait for a Command List to finish
117  *
118  * @param[in] cl_id: cl_id Command List ID
119  *
120  * @return 0 on success
121  *****************************************************************************************
122  */
123 int hal_gfx_wait_irq_cl(int cl_id);
124 
125 /**
126  *****************************************************************************************
127  * @brief Wait for a Breakpoint
128  *
129  * @param[in] brk_id: Breakpoint ID
130  *
131  * @return 0 on success
132  *****************************************************************************************
133  */
134 int hal_gfx_wait_irq_brk(int brk_id);
135 
136 /**
137  *****************************************************************************************
138  * @brief Read Hardware register
139  *
140  * @param[in] reg: Register to read
141  *
142  * @return Value read from the register
143  *****************************************************************************************
144  */
145 uint32_t hal_gfx_reg_read(uint32_t reg);
146 
147 /**
148  *****************************************************************************************
149  * @brief Write Hardware Register
150  *
151  * @param[in] reg: Register to write
152  * @param[in] value: Value to be written
153  *****************************************************************************************
154  */
155 void hal_gfx_reg_write(uint32_t reg, uint32_t value);
156 
157 /**
158  *****************************************************************************************
159  * @brief Create memory buffer
160  *
161  * @param[in] size: Size of buffer in bytes
162  *
163  * @return hal_gfx_buffer_t struct
164  *****************************************************************************************
165  */
166 hal_gfx_buffer_t hal_gfx_buffer_create(int size);
167 
168 /**
169  *****************************************************************************************
170  * @brief Create memory buffer at a specific pool
171  *
172  * @param[in] pool: ID of the desired memory pool
173  * @param[in] size: of buffer in bytes
174  *
175  * @return hal_gfx_buffer_t struct
176  *****************************************************************************************
177  */
178 hal_gfx_buffer_t hal_gfx_buffer_create_pool(int pool, int size);
179 
180 /**
181  *****************************************************************************************
182  * @brief Maps buffer
183  *
184  * @param[in] bo: Pointer to buffer struct
185  *
186  * @return Virtual pointer of the buffer (same as in bo->base_virt)
187  *****************************************************************************************
188  */
189 void *hal_gfx_buffer_map(hal_gfx_buffer_t *bo);
190 
191 /**
192  *****************************************************************************************
193  * @brief Unmaps buffer
194  *
195 * @param[in] bo: Pointer to buffer struct
196  *****************************************************************************************
197  */
198 void hal_gfx_buffer_unmap(hal_gfx_buffer_t *bo);
199 
200 /**
201  *****************************************************************************************
202  * @brief Destroy/deallocate buffer
203  *
204  * @param[in] bo: Pointer to buffer struct
205  *****************************************************************************************
206  */
207 void hal_gfx_buffer_destroy(hal_gfx_buffer_t *bo);
208 
209 /**
210  *****************************************************************************************
211  * @brief Get physical (GPU) base address of a given buffer
212  *
213  * @param[in] bo: Pointer to buffer struct
214  *
215  * @return Physical base address of a given buffer
216  *****************************************************************************************
217  */
218 uintptr_t hal_gfx_buffer_phys(hal_gfx_buffer_t *bo);
219 
220 /**
221  *****************************************************************************************
222  * @brief Write-back buffer from cache to main memory
223  *
224  * @param[in] bo: Pointer to buffer struct
225  *****************************************************************************************
226  */
227 void hal_gfx_buffer_flush(hal_gfx_buffer_t * bo);
228 
229 /**
230  *****************************************************************************************
231  * @brief Allocate memory for CPU to use (typically, standard malloc() is called)
232  *
233  * @param[in] size: Size in bytes
234  *
235  * @return Pointer to allocated memory (virtual)
236  *****************************************************************************************
237  */
238 void *hal_gfx_host_malloc(size_t size);
239 
240 /**
241  *****************************************************************************************
242  * @brief Free memory previously allocated with hal_gfx_host_malloc()
243  *
244  * @param[in] ptr: Pointer to allocated memory (virtual)
245  *****************************************************************************************
246  */
247 void hal_gfx_host_free(void *ptr );
248 
249 /**
250  *****************************************************************************************
251  * @brief Initialize Ring Buffer. Should be called from inside hal_gfx_sys_init().
252  * This is a private function, the user should never call it.
253  *
254  * @param[in] rb: Pointer to hal_gfx_ring_buffer_t struct
255  * @param[in] reset: Resets the Ring Buffer if non-zero
256  *
257  * @return Negative number on error
258  *****************************************************************************************
259  */
260 int hal_gfx_rb_init(hal_gfx_ringbuffer_t *rb, int reset);
261 
262 /**
263  *****************************************************************************************
264  * @brief Mutex Lock for multiple processes/threads
265  *
266  * @param[in] mutex_id: MUTEX_RB or MUTEX_MALLOC
267  *****************************************************************************************
268  */
269 int hal_gfx_mutex_lock(int mutex_id);
270 
271 /**
272  *****************************************************************************************
273  * @brief Mutex Unlock for multiple processes/threads
274  *
275  * @param[in] mutex_id: MUTEX_RB or MUTEX_MALLOC
276  *****************************************************************************************
277  */
278 int hal_gfx_mutex_unlock(int mutex_id);
279 /** @} */
280 
281 #ifdef __cplusplus
282 }
283 #endif
284 
285 #endif
286 /** @} */
287 /** @} */
288 /** @} */
289 
hal_gfx_sys_init
int32_t hal_gfx_sys_init(void)
Initialize system.
hal_gfx_reg_write
void hal_gfx_reg_write(uint32_t reg, uint32_t value)
Write Hardware Register.
hal_gfx_rb_init
int hal_gfx_rb_init(hal_gfx_ringbuffer_t *rb, int reset)
Initialize Ring Buffer.
hal_gfx_wait_irq_brk
int hal_gfx_wait_irq_brk(int brk_id)
Wait for a Breakpoint.
hal_gfx_buffer_t_::size
int size
Size of buffer.
Definition: hal_gfx_hal.h:76
hal_gfx_ringbuffer_t_
The ringbuffer structure.
Definition: hal_gfx_hal.h:84
hal_gfx_buffer_map
void * hal_gfx_buffer_map(hal_gfx_buffer_t *bo)
Maps buffer.
hal_gfx_ringbuffer_t_::bo
hal_gfx_buffer_t bo
Memory base structure.
Definition: hal_gfx_hal.h:85
hal_gfx_wait_irq_cl
int hal_gfx_wait_irq_cl(int cl_id)
Wait for a Command List to finish.
hal_gfx_mutex_unlock
int hal_gfx_mutex_unlock(int mutex_id)
Mutex Unlock for multiple processes/threads.
hal_gfx_buffer_create_pool
hal_gfx_buffer_t hal_gfx_buffer_create_pool(int pool, int size)
Create memory buffer at a specific pool.
hal_gfx_buffer_create
hal_gfx_buffer_t hal_gfx_buffer_create(int size)
Create memory buffer.
hal_gfx_sys_defs.h
hal_gfx_buffer_t_
The base structure of gpu memory.
Definition: hal_gfx_hal.h:75
hal_gfx_ringbuffer_t
struct hal_gfx_ringbuffer_t_ hal_gfx_ringbuffer_t
The ringbuffer structure.
hal_gfx_host_malloc
void * hal_gfx_host_malloc(size_t size)
Allocate memory for CPU to use (typically, standard malloc() is called)
hal_gfx_wait_irq
int hal_gfx_wait_irq(void)
Wait for interrupt from the GPU.
hal_gfx_buffer_t_::fd
int fd
File Descriptor of buffer.
Definition: hal_gfx_hal.h:77
hal_gfx_buffer_destroy
void hal_gfx_buffer_destroy(hal_gfx_buffer_t *bo)
Destroy/deallocate buffer.
hal_gfx_ringbuffer_t_::last_submission_id
int last_submission_id
Latest command list id.
Definition: hal_gfx_hal.h:87
hal_gfx_reg_read
uint32_t hal_gfx_reg_read(uint32_t reg)
Read Hardware register.
hal_gfx_buffer_t_::base_virt
void * base_virt
Virtual address of buffer.
Definition: hal_gfx_hal.h:78
hal_gfx_mutex_lock
int hal_gfx_mutex_lock(int mutex_id)
Mutex Lock for multiple processes/threads.
hal_gfx_buffer_flush
void hal_gfx_buffer_flush(hal_gfx_buffer_t *bo)
Write-back buffer from cache to main memory.
hal_gfx_buffer_phys
uintptr_t hal_gfx_buffer_phys(hal_gfx_buffer_t *bo)
Get physical (GPU) base address of a given buffer.
hal_gfx_buffer_unmap
void hal_gfx_buffer_unmap(hal_gfx_buffer_t *bo)
Unmaps buffer.
hal_gfx_ringbuffer_t_::offset
int offset
Record ringbuffer usage.
Definition: hal_gfx_hal.h:86
pool
memory pool structure
Definition: tsi_malloc_intern.h:100
hal_gfx_buffer_t
struct hal_gfx_buffer_t_ hal_gfx_buffer_t
The base structure of gpu memory.
hal_gfx_host_free
void hal_gfx_host_free(void *ptr)
Free memory previously allocated with hal_gfx_host_malloc()
hal_gfx_buffer_t_::base_phys
uintptr_t base_phys
Physical address of buffer.
Definition: hal_gfx_hal.h:79