Arm-2D  
2D Image Processing Library for Cortex-M Processors
 
Loading...
Searching...
No Matches
arm_2d.h
1/*
2 * Copyright (C) 2022 Arm Limited or its affiliates. All rights reserved.
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 *
6 * Licensed under the Apache License, Version 2.0 (the License); you may
7 * not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
14 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19/* ----------------------------------------------------------------------
20 * Project: Arm-2D Library
21 * Title: arm_2d.h
22 * Description: Public header file to contain the all avaialble Arm-2D
23 * interface header files
24 *
25 * $Date: 7 Jan 2026
26 * $Revision: V.1.2.6-dev
27 *
28 * Target Processor: Cortex-M cores
29 * -------------------------------------------------------------------- */
30
31#ifndef __ARM_2D_H__
32#define __ARM_2D_H__
33
34/*============================ INCLUDES ======================================*/
35#include "arm_2d_types.h"
36#include "arm_2d_op.h"
37#include "arm_2d_tile.h"
38#include "arm_2d_draw.h"
39#include "arm_2d_conversion.h"
40#include "arm_2d_alpha_blending.h"
41#include "arm_2d_transform.h"
42#include "arm_2d_filter.h"
43
44#ifdef __cplusplus
45extern "C" {
46#endif
47
48/* suppress some warnings for user applications when using arm-2d.
49 */
50#if defined(__clang__)
51# pragma clang diagnostic push
52# pragma clang diagnostic ignored "-Wunknown-warning-option"
53# pragma clang diagnostic ignored "-Wreserved-identifier"
54# pragma clang diagnostic ignored "-Wgnu-variable-sized-type-not-at-end"
55# pragma clang diagnostic ignored "-Wgnu-zero-variadic-macro-arguments"
56# pragma clang diagnostic ignored "-Wgnu-statement-expression"
57# pragma clang diagnostic ignored "-Wextra-semi-stmt"
58# pragma clang diagnostic ignored "-Wcompound-token-split-by-macro"
59# pragma clang diagnostic ignored "-Winitializer-overrides"
60# pragma clang diagnostic ignored "-Wgcc-compat"
61# pragma clang diagnostic ignored "-Wgnu-empty-initializer"
62# pragma clang diagnostic ignored "-Wshadow"
63# pragma clang diagnostic ignored "-Wconditional-uninitialized"
64# pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
65# pragma clang diagnostic ignored "-Wc23-extensions"
66# pragma clang diagnostic ignored "-Wunused-value"
67# pragma clang diagnostic ignored "-Wbad-function-cast"
68# pragma clang diagnostic ignored "-Wundef"
69#elif __IS_COMPILER_GCC__
70# pragma GCC diagnostic ignored "-Wpedantic"
71# pragma GCC diagnostic ignored "-Wmissing-braces"
72# pragma GCC diagnostic ignored "-Wunused-value"
73# pragma GCC diagnostic ignored "-Wnonnull-compare"
74# pragma GCC diagnostic ignored "-Wunused-but-set-variable"
75# pragma GCC diagnostic ignored "-Wunused-const-variable"
76#elif __IS_COMPILER_ARM_COMPILER_5__
77# pragma diag_suppress 1296,174,64,177,1
78#elif __IS_COMPILER_IAR__
79# pragma diag_suppress=Pa029,Pe301,Pe174,Pe191,Pe177,Pe546
80#endif
81
82/*!
83 * \addtogroup gKernel 1 Kernel
84 * @{
85 */
86
87/*============================ MACROS ========================================*/
88
89/* arm-2d version */
90#define ARM_2D_VERSION_MAJOR 1 //!< Major version
91#define ARM_2D_VERSION_MINOR 2 //!< Minor version
92#define ARM_2D_VERSION_PATCH 6 //!< Patch number
93#define ARM_2D_VERSION_STR "dev" //!< tag
94
95/*!
96 * \brief arm-2d version number in decimal
97 *
98 */
99#define ARM_2D_VERSION ( ARM_2D_VERSION_MAJOR * 10000ul \
100 + ARM_2D_VERSION_MINOR * 100ul \
101 + ARM_2D_VERSION_PATCH)
102
103/*============================ MACROFIED FUNCTIONS ===========================*/
104
105#define ARM_2D_OP_INIT(__OP) \
106 arm_2d_op_init((arm_2d_op_core_t *)&(__OP), sizeof(__OP))
107#define ARM_2D_OP_DEPOSE(__OP) \
108 arm_2d_op_depose((arm_2d_op_core_t *)&(__OP), sizeof(__OP))
109/*!
110 * \brief wait asynchronous operation complete
111 * \param[in] ... [OPTIONAL] the address of the target OP (NULL or ignore means using the default OP)
112 * \retval true sync up with operation
113 * \retval false operation is busy
114 */
115#define ARM_2D_OP_WAIT_ASYNC(...) \
116 arm_2d_op_wait_async((arm_2d_op_core_t *)(NULL,##__VA_ARGS__))
117
118/*============================ TYPES =========================================*/
119
120/*!
121 * \brief a type for arm-2d runtime configuration
122 *
123 */
124typedef struct {
125 /*! if the target region is out of the target tile, return arm_fsm_rt_cpl */
126 uint8_t TREAT_OUT_OF_RANGE_AS_COMPLETE : 1;
127
128 /*! indicate that there is a dedicated thread to run arm_2d_task() in RTOS env */
129 uint8_t HAS_DEDICATED_THREAD_FOR_2D_TASK : 1;
130 uint8_t : 6;
131} arm_2d_runtime_feature_t;
132
133/*!
134 * \brief a type for arm-2d version
135 *
136 */
137typedef struct {
138 uint8_t Major; //!< major version
139 uint8_t Minor; //!< minor version
140 uint8_t Patch; //!< patch number
141 uint8_t : 8;
142} arm_2d_version_t;
143
144/*============================ GLOBAL VARIABLES ==============================*/
145
146/*!
147 * \brief arm-2d runtime feature configuration
148 *
149 */
150extern
151arm_2d_runtime_feature_t ARM_2D_RUNTIME_FEATURE;
152
153/*!
154 * \brief arm-2d version
155 *
156 */
157extern
158const arm_2d_version_t ARM_2D_VERSION_INFO;
159
160/*============================ PROTOTYPES ====================================*/
161
162/*!
163 * \brief initialise arm-2d
164 */
165extern
166void arm_2d_init(void);
167
168/*!
169 * \brief set the default frame buffer
170 * \param ptFrameBuffer the new frame buffer,
171 * \note Passing NULL means using no default framebuffer
172 * \return arm_2d_tile_t* the address of the old frame buffer
173 */
174extern
175arm_2d_tile_t *arm_2d_set_default_frame_buffer(
176 const arm_2d_tile_t *ptFrameBuffer);
177
178/*!
179 * \brief get the default frame buffer
180 * \return arm_2d_tile_t* the address of the default frame buffer
181 */
182extern
183arm_2d_tile_t *arm_2d_get_default_frame_buffer(void);
184
185/*!
186 * \brief attach a user param (which could be a pointer) to specified OP
187 * \param ptOP the address of the target OP (NULL means using the default OP)
188 * \param pUserParam a user parameter (it can be used as a pointer)
189 */
190extern
191void arm_2d_set_user_param(arm_2d_op_core_t *ptOP, uintptr_t pUserParam);
192
193
194/*!
195 * \brief initialize an given opcode
196 * \param ptOP the address of the target OP
197 * \param tSize the size of the opcode object
198 * \return arm_2d_op_core_t * the address of the OP
199 */
200extern
201arm_2d_op_core_t *arm_2d_op_init(arm_2d_op_core_t *ptOP, size_t tSize);
202
203
204/*!
205 * \brief depose an given opcode
206 * \param ptOP the address of the target OP
207 * \param tSize the size of the opcode object
208 * \return arm_2d_op_core_t * the address of the OP
209 */
210extern
211arm_2d_op_core_t *arm_2d_op_depose(arm_2d_op_core_t *ptOP, size_t tSize);
212
213/*!
214 * \brief attach a semaphore (which could be a pointer) to specified OP
215 * \param ptOP the address of the target OP (NULL means using the default OP)
216 * \param pSemaphore a pointer points to a RTOS semaphore
217 * \note this API only available when __ARM_2D_HAS_ASYNC__ is 1
218 */
219extern
220void arm_2d_op_attach_semaphore(arm_2d_op_core_t *ptOP, uintptr_t pSemaphore);
221
222/*!
223 * \brief get the attached semaphore (which could be a pointer) from specified OP
224 * \param ptOP the address of the target OP (NULL means using the default OP)
225 * \return uintptr_t the semaphore
226 * \note this API only available when __ARM_2D_HAS_ASYNC__ is 1
227 */
228extern
229uintptr_t arm_2d_op_get_semaphore(arm_2d_op_core_t *ptOP);
230
231/*!
232 * \brief wait asynchronous operation complete
233 * \param[in] ptOP the address of the target OP (NULL means using the default OP)
234 * \retval true sync up with operation
235 * \retval false operation is busy
236 */
237extern
238bool arm_2d_op_wait_async(arm_2d_op_core_t *ptOP);
239
240/*!
241 \brief get the status of a specified OP,
242 \details usually, it is used after calling arm_2d_op_wait_async().
243 E.g.
244 \code
245 //! wait for previous operation complete
246 do {
247 arm_2d_op_wait_async();
248 arm_2d_op_status_t tStatus = arm_2d_get_op_status();
249 if (tStatus.bIOError) {
250 //! error detected
251 ...
252 } else if (tStatus.bOpCpl) {
253 break;
254 }
255 } while(true);
256 \endcode
257 \param ptOP the address of the target OP (NULL means using the default OP)
258 \return arm_2d_op_status_t the operation status
259 */
260extern
261arm_2d_op_status_t arm_2d_get_op_status(arm_2d_op_core_t *ptOP);
262
263/*!
264 * \brief arm-2d pixel pipeline task entery
265 * \note This function is *TRHEAD-SAFE*
266 * \param ptTask the address of an arm-2d task control block
267 * \retval arm_fsm_rt_cpl The sub-task FIFO is empty, the caller can wait for a
268 * semaphore set by arm_2d_notif_sub_task_fifo_task_arrive()
269 * \retval arm_fsm_rt_on_going The arm_2d_task yields
270 * \retval arm_fsm_rt_async You shouldn't see this value
271 * \retval arm_fsm_rt_wait_for_obj hardware accelerator wants to sync-up with applications.
272 * \retval (<0) Serious error is detected.
273 */
274extern
275arm_fsm_rt_t arm_2d_task(arm_2d_task_t *ptTask);
276
277/*!
278 * \brief allocate a memory block with specified memory type
279 *
280 * \param wSize the minimal size
281 * \param nAlign the alignment
282 * \param tType the type of memory
283 * \return void* the memory address
284 */
285extern
286void *__arm_2d_allocate_scratch_memory( uint32_t wSize,
287 uint_fast8_t nAlign,
288 arm_2d_mem_type_t tType);
289/*!
290 * \brief free a specified memory block
291 *
292 * \param tType the type of memory
293 * \param pBuff the address of the memory
294 */
295extern
296void __arm_2d_free_scratch_memory( arm_2d_mem_type_t tType,
297 void *pBuff);
298
299/*!
300 * \brief allocate a scratch memory and initialize arm_2d_scratch_mem_t object
301 *
302 * \param[out] ptMemory the address of an arm_2d_scratch_mem_t object to hold
303 * the result
304 * \param[in] hwItemSize the size of each item
305 * \param[in] hwItemCount the number of items
306 * \param[in] hwAlignment the alignment requirement
307 * \param[in] tType the type of memory
308 * \return arm_2d_scratch_mem_t* the initialized the arm_2d_scratch_mem_t object
309 * address. NULL means failed to allocate scratch memory
310 */
311extern
312ARM_NONNULL(1)
313arm_2d_scratch_mem_t *arm_2d_scratch_memory_new(arm_2d_scratch_mem_t *ptMemory,
314 uint16_t hwItemSize,
315 uint16_t hwItemCount,
316 uint16_t hwAlignment,
317 arm_2d_mem_type_t tType);
318
319
320/*!
321 * \brief free a scratch memory with a given scratch memory descriptor object
322 *
323 * \param[in] the target scratch memory descriptor
324 * \return arm_2d_scratch_mem_t * the de-initialized the scratch memory descriptor
325 */
326extern
327ARM_NONNULL(1)
328arm_2d_scratch_mem_t *arm_2d_scratch_memory_free(arm_2d_scratch_mem_t *ptMemory);
329
330/*! @} */
331
332/*! \note delibrately comment out */
333//#if defined(__clang__)
334//# pragma clang diagnostic pop
335//#endif
336
337#ifdef __cplusplus
338}
339#endif
340
341
342#endif