2D Image Processing Library for Cortex-M Processors
•All Data Structures Functions Variables Typedefs Enumerations Enumerator Modules Pages
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: #include "arm_2d.h"
22 * Description: Public header file to contain the all avaialble Arm-2D
23 * interface header files
24 *
25 * $Date: 01. Dec 2023
26 * $Revision: V.1.1.5
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
43#ifdef __cplusplus
44extern "C" {
45#endif
46
47/* suppress some warnings for user applications when using arm-2d.
48 */
49#if defined(__clang__)
50# pragma clang diagnostic push
51# pragma clang diagnostic ignored "-Wunknown-warning-option"
52# pragma clang diagnostic ignored "-Wreserved-identifier"
53# pragma clang diagnostic ignored "-Wgnu-variable-sized-type-not-at-end"
54# pragma clang diagnostic ignored "-Wgnu-zero-variadic-macro-arguments"
55# pragma clang diagnostic ignored "-Wgnu-statement-expression"
56# pragma clang diagnostic ignored "-Wextra-semi-stmt"
57# pragma clang diagnostic ignored "-Wcompound-token-split-by-macro"
58# pragma clang diagnostic ignored "-Winitializer-overrides"
59# pragma clang diagnostic ignored "-Wgcc-compat"
60# pragma clang diagnostic ignored "-Wgnu-empty-initializer"
61# pragma clang diagnostic ignored "-Wshadow"
62# pragma clang diagnostic ignored "-Wconditional-uninitialized"
63# pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
64# pragma clang diagnostic ignored "-Wc23-extensions"
65# pragma clang diagnostic ignored "-Wunused-value"
66#elif __IS_COMPILER_GCC__
67# pragma GCC diagnostic ignored "-Wpedantic"
68# pragma GCC diagnostic ignored "-Wmissing-braces"
69# pragma GCC diagnostic ignored "-Wunused-value"
70#elif defined(__IS_COMPILER_ARM_COMPILER_5__)
71# pragma diag_suppress 1296,174,64,177
72#endif
73
74/*!
75 * \addtogroup gKernel 1 Kernel
76 * @{
77 */
78
79/*============================ MACROS ========================================*/
80
81/* arm-2d version */
82#define ARM_2D_VERSION_MAJOR 1 //!< Major version
83#define ARM_2D_VERSION_MINOR 1 //!< Minor version
84#define ARM_2D_VERSION_PATCH 5 //!< Patch number
85#define ARM_2D_VERSION_STR "" //!< tag
86
87/*!
88 * \brief arm-2d version number in decimal
89 *
90 */
91#define ARM_2D_VERISON ( ARM_2D_VERSION_MAJOR * 10000ul \
92 + ARM_2D_VERSION_MINOR * 100ul \
93 + ARM_2D_VERSION_PATCH)
94
95/*============================ MACROFIED FUNCTIONS ===========================*/
96
97#define ARM_2D_OP_INIT(__OP) \
98 arm_2d_op_init((arm_2d_op_core_t *)&(__OP), sizeof(__OP))
99#define ARM_2D_OP_DEPOSE(__OP) \
100 arm_2d_op_depose((arm_2d_op_core_t *)&(__OP), sizeof(__OP))
101/*!
102 * \brief wait asynchronous operation complete
103 * \param[in] ... [OPTIONAL] the address of the target OP (NULL or ignore means using the default OP)
104 * \retval true sync up with operation
105 * \retval false operation is busy
106 */
107#define ARM_2D_OP_WAIT_ASYNC(...) \
108 arm_2d_op_wait_async((arm_2d_op_core_t *)(NULL,##__VA_ARGS__))
109
110/*============================ TYPES =========================================*/
111
112/*!
113 * \brief a type for arm-2d runtime configuration
114 *
115 */
116typedef struct {
117 /*! if the target region is out of the target tile, return arm_fsm_rt_cpl */
118 uint8_t TREAT_OUT_OF_RANGE_AS_COMPLETE : 1;
119
120 /*! indicate that there is a dedicated thread to run arm_2d_task() in RTOS env */
121 uint8_t HAS_DEDICATED_THREAD_FOR_2D_TASK : 1;
122 uint8_t : 6;
123} arm_2d_runtime_feature_t;
124
125/*!
126 * \brief a type for arm-2d version
127 *
128 */
129typedef struct {
130 uint8_t Major; //!< major version
131 uint8_t Minor; //!< minor version
132 uint8_t Patch; //!< patch number
133 uint8_t : 8;
134} arm_2d_version_t;
135
136/*============================ GLOBAL VARIABLES ==============================*/
137
138/*!
139 * \brief arm-2d runtime feature configuration
140 *
141 */
142extern
143arm_2d_runtime_feature_t ARM_2D_RUNTIME_FEATURE;
144
145/*!
146 * \brief arm-2d version
147 *
148 */
149extern
150const arm_2d_version_t ARM_2D_VERSION;
151
152/*============================ PROTOTYPES ====================================*/
153
154/*!
155 * \brief initialise arm-2d
156 */
157extern
158void arm_2d_init(void);
159
160/*!
161 * \brief set the default frame buffer
162 * \param ptFrameBuffer the new frame buffer,
163 * \note Passing NULL means using no default framebuffer
164 * \return arm_2d_tile_t* the address of the old frame buffer
165 */
166extern
167arm_2d_tile_t *arm_2d_set_default_frame_buffer(
168 const arm_2d_tile_t *ptFrameBuffer);
169
170/*!
171 * \brief get the default frame buffer
172 * \return arm_2d_tile_t* the address of the default frame buffer
173 */
174extern
175arm_2d_tile_t *arm_2d_get_default_frame_buffer(void);
176
177/*!
178 * \brief attach a user param (which could be a pointer) to specified OP
179 * \param ptOP the address of the target OP (NULL means using the default OP)
180 * \param pUserParam a user parameter (it can be used as a pointer)
181 */
182extern
183void arm_2d_set_user_param(arm_2d_op_core_t *ptOP, uintptr_t pUserParam);
184
185
186/*!
187 * \brief initialize an given opcode
188 * \param ptOP the address of the target OP
189 * \param tSize the size of the opcode object
190 * \return arm_2d_op_core_t * the address of the OP
191 */
192extern
193arm_2d_op_core_t *arm_2d_op_init(arm_2d_op_core_t *ptOP, size_t tSize);
194
195
196/*!
197 * \brief depose an given opcode
198 * \param ptOP the address of the target OP
199 * \param tSize the size of the opcode object
200 * \return arm_2d_op_core_t * the address of the OP
201 */
202extern
203arm_2d_op_core_t *arm_2d_op_depose(arm_2d_op_core_t *ptOP, size_t tSize);
204
205/*!
206 * \brief attach a semaphore (which could be a pointer) to specified OP
207 * \param ptOP the address of the target OP (NULL means using the default OP)
208 * \param pSemaphore a pointer points to a RTOS semaphore
209 * \note this API only available when __ARM_2D_HAS_ASYNC__ is 1
210 */
211extern
212void arm_2d_op_attach_semaphore(arm_2d_op_core_t *ptOP, uintptr_t pSemaphore);
213
214/*!
215 * \brief get the attached semaphore (which could be a pointer) from specified OP
216 * \param ptOP the address of the target OP (NULL means using the default OP)
217 * \return uintptr_t the semaphore
218 * \note this API only available when __ARM_2D_HAS_ASYNC__ is 1
219 */
220extern
221uintptr_t arm_2d_op_get_semaphore(arm_2d_op_core_t *ptOP);
222
223/*!
224 * \brief wait asynchronous operation complete
225 * \param[in] ptOP the address of the target OP (NULL means using the default OP)
226 * \retval true sync up with operation
227 * \retval false operation is busy
228 */
229extern
230bool arm_2d_op_wait_async(arm_2d_op_core_t *ptOP);
231
232/*!
233 \brief get the status of a specified OP,
234 \details usually, it is used after calling arm_2d_op_wait_async().
235 E.g.
236 \code
237 //! wait for previous operation complete
238 do {
239 arm_2d_op_wait_async();
240 arm_2d_op_status_t tStatus = arm_2d_get_op_status();
241 if (tStatus.bIOError) {
242 //! error detected
243 ...
244 } else if (tStatus.bOpCpl) {
245 break;
246 }
247 } while(true);
248 \endcode
249 \param ptOP the address of the target OP (NULL means using the default OP)
250 \return arm_2d_op_status_t the operation status
251 */
252extern
253arm_2d_op_status_t arm_2d_get_op_status(arm_2d_op_core_t *ptOP);
254
255/*!
256 * \brief arm-2d pixel pipeline task entery
257 * \note This function is *TRHEAD-SAFE*
258 * \param ptTask the address of an arm-2d task control block
259 * \retval arm_fsm_rt_cpl The sub-task FIFO is empty, the caller can wait for a
260 * semaphore set by arm_2d_notif_sub_task_fifo_task_arrive()
261 * \retval arm_fsm_rt_on_going The arm_2d_task yields
262 * \retval arm_fsm_rt_async You shouldn't see this value
263 * \retval arm_fsm_rt_wait_for_obj hardware accelerator wants to sync-up with applications.
264 * \retval (<0) Serious error is detected.
265 */
266extern
267arm_fsm_rt_t arm_2d_task(arm_2d_task_t *ptTask);
268
269/*! @} */
270
271/*! \note delibrately comment out */
272//#if defined(__clang__)
273//# pragma clang diagnostic pop
274//#endif
275
276#ifdef __cplusplus
277}
278#endif
279
280
281#endif