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: 12. May 2023
26 * $Revision: V.1.1.3
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#elif __IS_COMPILER_GCC__
64# pragma GCC diagnostic ignored "-Wpedantic"
65# pragma GCC diagnostic ignored "-Wmissing-braces"
66#elif defined(__IS_COMPILER_ARM_COMPILER_5__)
67# pragma diag_suppress 1296,174
68#endif
69
70/*!
71 * \addtogroup gKernel 1 Kernel
72 * @{
73 */
74
75/*============================ MACROS ========================================*/
76
77/* arm-2d version */
78#define ARM_2D_VERSION_MAJOR 1 //!< Major version
79#define ARM_2D_VERSION_MINOR 1 //!< Minor version
80#define ARM_2D_VERSION_PATCH 3 //!< Patch number
81#define ARM_2D_VERSION_STR "" //!< tag
82
83/*!
84 * \brief arm-2d version number in decimal
85 *
86 */
87#define ARM_2D_VERISON ( ARM_2D_VERSION_MAJOR * 10000ul \
88 + ARM_2D_VERSION_MINOR * 100ul \
89 + ARM_2D_VERSION_PATCH)
90
91/*============================ MACROFIED FUNCTIONS ===========================*/
92
93#define ARM_2D_OP_INIT(__OP) \
94 arm_2d_op_init((arm_2d_op_core_t *)&(__OP), sizeof(__OP))
95#define ARM_2D_OP_DEPOSE(__OP) \
96 arm_2d_op_depose((arm_2d_op_core_t *)&(__OP), sizeof(__OP))
97
98/*============================ TYPES =========================================*/
99
100/*!
101 * \brief a type for arm-2d runtime configuration
102 *
103 */
104typedef struct {
105 /*! if the target region is out of the target tile, return arm_fsm_rt_cpl */
106 uint8_t TREAT_OUT_OF_RANGE_AS_COMPLETE : 1;
107
108 /*! indicate that there is a dedicated thread to run arm_2d_task() in RTOS env */
109 uint8_t HAS_DEDICATED_THREAD_FOR_2D_TASK : 1;
110 uint8_t : 6;
111} arm_2d_runtime_feature_t;
112
113/*!
114 * \brief a type for arm-2d version
115 *
116 */
117typedef struct {
118 uint8_t Major; //!< major version
119 uint8_t Minor; //!< minor version
120 uint8_t Patch; //!< patch number
121 uint8_t : 8;
122} arm_2d_version_t;
123
124/*============================ GLOBAL VARIABLES ==============================*/
125
126/*!
127 * \brief arm-2d runtime feature configuration
128 *
129 */
130extern
131arm_2d_runtime_feature_t ARM_2D_RUNTIME_FEATURE;
132
133/*!
134 * \brief arm-2d version
135 *
136 */
137extern
138const arm_2d_version_t ARM_2D_VERSION;
139
140/*============================ PROTOTYPES ====================================*/
141
142/*!
143 * \brief initialise arm-2d
144 */
145extern
146void arm_2d_init(void);
147
148/*!
149 * \brief set the default frame buffer
150 * \param ptFrameBuffer the new frame buffer,
151 * \note Passing NULL means using no default framebuffer
152 * \return arm_2d_tile_t* the address of the old frame buffer
153 */
154extern
155arm_2d_tile_t *arm_2d_set_default_frame_buffer(
156 const arm_2d_tile_t *ptFrameBuffer);
157
158/*!
159 * \brief get the default frame buffer
160 * \return arm_2d_tile_t* the address of the default frame buffer
161 */
162extern
163arm_2d_tile_t *arm_2d_get_default_frame_buffer(void);
164
165/*!
166 * \brief attach a user param (which could be a pointer) to specified OP
167 * \param ptOP the address of the target OP (NULL means using the default OP)
168 * \param pUserParam a user parameter (it can be used as a pointer)
169 */
170extern
171void arm_2d_set_user_param(arm_2d_op_core_t *ptOP, uintptr_t pUserParam);
172
173
174/*!
175 * \brief initialize an given opcode
176 * \param ptOP the address of the target OP
177 * \param tSize the size of the opcode object
178 * \return arm_2d_op_core_t * the address of the OP
179 */
180extern
181arm_2d_op_core_t *arm_2d_op_init(arm_2d_op_core_t *ptOP, size_t tSize);
182
183
184/*!
185 * \brief depose an given opcode
186 * \param ptOP the address of the target OP
187 * \param tSize the size of the opcode object
188 * \return arm_2d_op_core_t * the address of the OP
189 */
190extern
191arm_2d_op_core_t *arm_2d_op_depose(arm_2d_op_core_t *ptOP, size_t tSize);
192
193/*!
194 * \brief attach a semaphore (which could be a pointer) to specified OP
195 * \param ptOP the address of the target OP (NULL means using the default OP)
196 * \param pSemaphore a pointer points to a RTOS semaphore
197 * \note this API only available when __ARM_2D_HAS_ASYNC__ is 1
198 */
199extern
200void arm_2d_op_attach_semaphore(arm_2d_op_core_t *ptOP, uintptr_t pSemaphore);
201
202/*!
203 * \brief get the attached semaphore (which could be a pointer) from specified OP
204 * \param ptOP the address of the target OP (NULL means using the default OP)
205 * \return uintptr_t the semaphore
206 * \note this API only available when __ARM_2D_HAS_ASYNC__ is 1
207 */
208extern
209uintptr_t arm_2d_op_get_semaphore(arm_2d_op_core_t *ptOP);
210
211/*!
212 * \brief wait asynchronous operation complete
213 * \param[in] ptOP the address of the target OP (NULL means using the default OP)
214 * \retval true sync up with operation
215 * \retval false operation is busy
216 */
217extern
218bool arm_2d_op_wait_async(arm_2d_op_core_t *ptOP);
219
220/*!
221 \brief get the status of a specified OP,
222 \details usually, it is used after calling arm_2d_op_wait_async().
223 E.g.
224 \code
225 //! wait for previous operation complete
226 do {
227 arm_2d_op_wait_async();
228 arm_2d_op_status_t tStatus = arm_2d_get_op_status();
229 if (tStatus.bIOError) {
230 //! error detected
231 ...
232 } else if (tStatus.bOpCpl) {
233 break;
234 }
235 } while(true);
236 \endcode
237 \param ptOP the address of the target OP (NULL means using the default OP)
238 \return arm_2d_op_status_t the operation status
239 */
240extern
241arm_2d_op_status_t arm_2d_get_op_status(arm_2d_op_core_t *ptOP);
242
243/*!
244 * \brief arm-2d pixel pipeline task entery
245 * \note This function is *TRHEAD-SAFE*
246 * \param ptTask the address of an arm-2d task control block
247 * \retval arm_fsm_rt_cpl The sub-task FIFO is empty, the caller can wait for a
248 * semaphore set by arm_2d_notif_sub_task_fifo_task_arrive()
249 * \retval arm_fsm_rt_on_going The arm_2d_task yields
250 * \retval arm_fsm_rt_async You shouldn't see this value
251 * \retval arm_fsm_rt_wait_for_obj hardware accelerator wants to sync-up with applications.
252 * \retval (<0) Serious error is detected.
253 */
254extern
255arm_fsm_rt_t arm_2d_task(arm_2d_task_t *ptTask);
256
257/*! @} */
258
259/*! \note delibrately comment out */
260//#if defined(__clang__)
261//# pragma clang diagnostic pop
262//#endif
263
264#ifdef __cplusplus
265}
266#endif
267
268
269#endif