hal_gfx_cmdlist.h
Go to the documentation of this file.
1 /**
2  ****************************************************************************************
3  *
4  * @file hal_gfx_cmdlist.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_CMDLIST GFX CMDLIST
47  * @brief GPU management interfaces of command list.
48  * @{
49  */
50 
51 #ifndef HAL_GFX_CMDLIST_H__
52 #define HAL_GFX_CMDLIST_H__
53 
54 #include "hal_gfx_sys_defs.h"
55 #include "hal_gfx_hal.h"
56 
57 #ifdef __cplusplus
58 extern "C" {
59 #endif
60 
61 /**
62  * @defgroup HAL_GFX_CMDLIST_MACRO Defines
63  * @{
64  */
65 #define CL_NOP 0x010000U /**< No operation. */
66 #define CL_PUSH 0x020000U /**< Push command to currently command list. */
67 #define CL_RETURN 0x040000U /**< Return from current command list. */
68 #define CL_ABORT 0x080000U /**< Abort current command list. */
69 #define CL_BATCH_SHIFT 12 /**< TODO. */
70 #define CL_BATCH_LOOP 0x8000 /**< TODO. */
71 #define SUBMISSION_ID_MASK 0xffffff /**< Mask. */
72 /** @} */
73 
74 /**
75  * @defgroup HAL_GFX_CMDLIST_STRUCT Structures
76  * @{
77  */
78 /**@brief Command list structure. */
79 typedef struct hal_gfx_cmdlist_t_
80 {
81  hal_gfx_buffer_t bo; /**< Buffer of command list*/
82  int size; /**< Number of entries in the command list */
83  int offset; /**< Points to the next address to write */
84  uint32_t flags; /**< Flags */
85  int32_t submission_id; /**< Command list id. */
86  struct hal_gfx_cmdlist_t_ *next; /**< Points to next command list */
87  struct hal_gfx_cmdlist_t_ *root; /**< Points to the head of the list */
88 } hal_gfx_cmdlist_t;
89 /** @} */
90 
91 /**
92  * @defgroup HAL_GFX_CMDLIST_FUNCTION Functions
93  * @{
94  */
95 /**
96  *****************************************************************************************
97  * @brief Create a new Command List into a preallocated space
98  *
99  * @param[in] bo: Command List buffer (preallocated)
100  *
101  * @return The instance of the new Command List
102  *****************************************************************************************
103  */
104 hal_gfx_cmdlist_t hal_gfx_cl_create_prealloc(hal_gfx_buffer_t *bo);
105 
106 /**
107  *****************************************************************************************
108  * @brief Create a new, non expandable Command List of specific size
109  *
110  * @param[in] size_bytes: Command List's size in bytes
111  *
112  * @return instance of the new Command List
113  *****************************************************************************************
114  */
115 hal_gfx_cmdlist_t hal_gfx_cl_create_sized(int size_bytes);
116 
117 /**
118  *****************************************************************************************
119  * @brief Create a new expandable Command List
120  *
121  * @return instance of the new Command List
122  *****************************************************************************************
123  */
124 hal_gfx_cmdlist_t hal_gfx_cl_create(void);
125 
126 
127 /**
128  *****************************************************************************************
129  * @brief Create a new expandable Command List with power management mode
130  *
131  * @return instance of the new Command List
132  *****************************************************************************************
133  */
134 hal_gfx_cmdlist_t hal_gfx_cl_le_create(void);
135 
136 /**
137  *****************************************************************************************
138  * @brief Destroy/Free a Command List
139  *
140  * @param[in] cl: Pointer to the Command List
141  *****************************************************************************************
142  */
143 void hal_gfx_cl_destroy(hal_gfx_cmdlist_t *cl);
144 
145 
146 /**
147  *****************************************************************************************
148  * @brief Destroy/Free a Command List with power management mode
149  *
150  * @param[in] cl: Pointer to the Command List
151  *****************************************************************************************
152  */
153 void hal_gfx_cl_le_destroy(hal_gfx_cmdlist_t *cl);
154 
155 /**
156  *****************************************************************************************
157  * @brief Reset position of next command to be written to the beginning. Doesn't clear the List's contents.
158  *
159  * @param[in] cl: Pointer to the Command List
160  *****************************************************************************************
161  */
162 void hal_gfx_cl_rewind(hal_gfx_cmdlist_t *cl);
163 
164 /**
165  *****************************************************************************************
166  * @brief Define in which Command List each subsequent commands are going to be inserted.
167  *
168  * @param[in] cl: Pointer to the Command List
169  *****************************************************************************************
170  */
171 void hal_gfx_cl_bind(hal_gfx_cmdlist_t *cl);
172 
173 /**
174  *****************************************************************************************
175  * @brief Define in which Command List each subsequent commands are going to be inserted.
176  * Bind this command list as Circular. It never gets full, it never expands,
177  * it may get implicitly submitted, it cannot be reused.
178  *
179  * @param[in] cl: Pointer to the Command List
180  *****************************************************************************************
181  */
182 void hal_gfx_cl_bind_circular(hal_gfx_cmdlist_t *cl);
183 
184 /**
185  *****************************************************************************************
186  * @brief Unbind current bound Command List, if any.
187  * @return None
188  *****************************************************************************************
189  */
190 void hal_gfx_cl_unbind(void);
191 
192 /**
193  *****************************************************************************************
194  * @brief Get bound Command List
195  *
196  * @return Pointer to the bound Command List
197  *****************************************************************************************
198  */
199 hal_gfx_cmdlist_t *hal_gfx_cl_get_bound(void);
200 
201 /**
202  *****************************************************************************************
203  * @brief Push command to command list, but do not trigger interrupt.
204  *
205  * @param[in] cl: command list
206  *****************************************************************************************
207  */
208 void hal_gfx_cl_submit_no_irq(hal_gfx_cmdlist_t *cl);
209 
210 /**
211  *****************************************************************************************
212  * @brief Enqueue Command List to the Ring Buffer for execution
213  *
214  * @param[in] cl: Pointer to the Command List
215  *****************************************************************************************
216  */
217 void hal_gfx_cl_submit(hal_gfx_cmdlist_t *cl);
218 
219 /**
220  *****************************************************************************************
221  * @brief Wait for Command List to finish
222  *
223  * @param[in] cl: Pointer to the Command List
224  *
225  * @return 0 if no error has occurred
226  *****************************************************************************************
227  */
228 int hal_gfx_cl_wait(hal_gfx_cmdlist_t *cl);
229 
230 /**
231  *****************************************************************************************
232  * @brief Add a command to the bound Command List
233  *
234  * @param[in] reg: Hardware register to be written
235  * @param[in] data: Data to be written
236  *****************************************************************************************
237  */
238 void hal_gfx_cl_add_cmd(uint32_t reg, uint32_t data);
239 
240 /**
241  *****************************************************************************************
242  * @brief Add multiple commands to the bound Command List
243  *
244  * @param[in] cmd_no: Numbers of commands to add
245  * @param[in] cmd: Pointer to the commands to be added
246  *
247  * @return 0 if no error has occurred
248  *****************************************************************************************
249  */
250 int hal_gfx_cl_add_multiple_cmds(int cmd_no, uint32_t *cmd);
251 
252 /**
253  *****************************************************************************************
254  * @brief Request free space from command list.
255  *
256  * @param[in] cmd_no: Number of commands to write
257  *
258  * @return Return pointer in bound_cl to directly add commands
259  *****************************************************************************************
260  */
261 uint32_t * hal_gfx_cl_get_space(int cmd_no);
262 
263 /**
264  *****************************************************************************************
265  * @brief Branch from the bound Command List to a different one. Return is implied.
266  *
267  * @param[in] cl: Pointer to the Command List to branch to
268  *****************************************************************************************
269  */
270 void hal_gfx_cl_branch(hal_gfx_cmdlist_t *cl);
271 
272 /**
273  *****************************************************************************************
274  * @brief Jump from the bound Command List to a different one. No return is implied.
275  *
276  * @param[in] cl: Pointer to the Command List to jump to
277  *****************************************************************************************
278  */
279 void hal_gfx_cl_jump(hal_gfx_cmdlist_t *cl);
280 
281 /**
282  *****************************************************************************************
283  * @brief Add an explicit return command to the bound Command List
284  *****************************************************************************************
285  */
286 void hal_gfx_cl_return(void);
287 
288 /**
289  *****************************************************************************************
290  * @brief Returns positive number if the Command List is almost full, otherwise returns 0.
291  *
292  * @param[in] cl: Pointer to the Command List
293  *****************************************************************************************
294  */
295 int hal_gfx_cl_almost_full(hal_gfx_cmdlist_t *cl);
296 
297 /**
298  *****************************************************************************************
299  * @brief Check if there is enough space or expansion can be performed for
300  * required commands.
301  *
302  * @param[in] cmd_no: Numbers of commands to be checked if they fit
303  *
304  * @return zero is commands fit or expansion xan be performed else return negative
305  *****************************************************************************************
306  */
307 int hal_gfx_cl_enough_space(int cmd_no);
308 /** @} */
309 #ifdef __cplusplus
310 }
311 #endif
312 
313 #endif
314 /** @} */
315 /** @} */
316 /** @} */
317 
hal_gfx_cl_unbind
void hal_gfx_cl_unbind(void)
Unbind current bound Command List, if any.
hal_gfx_cl_jump
void hal_gfx_cl_jump(hal_gfx_cmdlist_t *cl)
Jump from the bound Command List to a different one.
hal_gfx_cl_get_bound
hal_gfx_cmdlist_t * hal_gfx_cl_get_bound(void)
Get bound Command List.
hal_gfx_cmdlist_t_::bo
hal_gfx_buffer_t bo
Buffer of command list.
Definition: hal_gfx_cmdlist.h:81
hal_gfx_cl_le_create
hal_gfx_cmdlist_t hal_gfx_cl_le_create(void)
Create a new expandable Command List with power management mode.
hal_gfx_cmdlist_t_::next
struct hal_gfx_cmdlist_t_ * next
Points to next command list.
Definition: hal_gfx_cmdlist.h:86
hal_gfx_cl_bind
void hal_gfx_cl_bind(hal_gfx_cmdlist_t *cl)
Define in which Command List each subsequent commands are going to be inserted.
hal_gfx_cl_destroy
void hal_gfx_cl_destroy(hal_gfx_cmdlist_t *cl)
Destroy/Free a Command List.
hal_gfx_cl_wait
int hal_gfx_cl_wait(hal_gfx_cmdlist_t *cl)
Wait for Command List to finish.
hal_gfx_cl_get_space
uint32_t * hal_gfx_cl_get_space(int cmd_no)
Request free space from command list.
hal_gfx_cl_add_cmd
void hal_gfx_cl_add_cmd(uint32_t reg, uint32_t data)
Add a command to the bound Command List.
hal_gfx_cmdlist_t_
Command list structure.
Definition: hal_gfx_cmdlist.h:80
hal_gfx_cmdlist_t_::submission_id
int32_t submission_id
Command list id.
Definition: hal_gfx_cmdlist.h:85
hal_gfx_sys_defs.h
hal_gfx_cl_enough_space
int hal_gfx_cl_enough_space(int cmd_no)
Check if there is enough space or expansion can be performed for required commands.
hal_gfx_buffer_t_
The base structure of gpu memory.
Definition: hal_gfx_hal.h:75
hal_gfx_cl_le_destroy
void hal_gfx_cl_le_destroy(hal_gfx_cmdlist_t *cl)
Destroy/Free a Command List with power management mode.
hal_gfx_cl_submit
void hal_gfx_cl_submit(hal_gfx_cmdlist_t *cl)
Enqueue Command List to the Ring Buffer for execution.
hal_gfx_cmdlist_t_::offset
int offset
Points to the next address to write.
Definition: hal_gfx_cmdlist.h:83
hal_gfx_cmdlist_t
struct hal_gfx_cmdlist_t_ hal_gfx_cmdlist_t
Command list structure.
hal_gfx_cl_return
void hal_gfx_cl_return(void)
Add an explicit return command to the bound Command List.
hal_gfx_cl_almost_full
int hal_gfx_cl_almost_full(hal_gfx_cmdlist_t *cl)
Returns positive number if the Command List is almost full, otherwise returns 0.
hal_gfx_cl_create
hal_gfx_cmdlist_t hal_gfx_cl_create(void)
Create a new expandable Command List.
hal_gfx_cl_bind_circular
void hal_gfx_cl_bind_circular(hal_gfx_cmdlist_t *cl)
Define in which Command List each subsequent commands are going to be inserted.
hal_gfx_cmdlist_t_::flags
uint32_t flags
Flags.
Definition: hal_gfx_cmdlist.h:84
hal_gfx_cl_add_multiple_cmds
int hal_gfx_cl_add_multiple_cmds(int cmd_no, uint32_t *cmd)
Add multiple commands to the bound Command List.
hal_gfx_cmdlist_t_::root
struct hal_gfx_cmdlist_t_ * root
Points to the head of the list.
Definition: hal_gfx_cmdlist.h:87
hal_gfx_cl_create_sized
hal_gfx_cmdlist_t hal_gfx_cl_create_sized(int size_bytes)
Create a new, non expandable Command List of specific size.
hal_gfx_cmdlist_t_::size
int size
Number of entries in the command list.
Definition: hal_gfx_cmdlist.h:82
hal_gfx_cl_rewind
void hal_gfx_cl_rewind(hal_gfx_cmdlist_t *cl)
Reset position of next command to be written to the beginning.
hal_gfx_cl_create_prealloc
hal_gfx_cmdlist_t hal_gfx_cl_create_prealloc(hal_gfx_buffer_t *bo)
Create a new Command List into a preallocated space.
hal_gfx_cl_submit_no_irq
void hal_gfx_cl_submit_no_irq(hal_gfx_cmdlist_t *cl)
Push command to command list, but do not trigger interrupt.
hal_gfx_cl_branch
void hal_gfx_cl_branch(hal_gfx_cmdlist_t *cl)
Branch from the bound Command List to a different one.
hal_gfx_hal.h
Header file containing functions prototypes of Graphics library.