Arm-2D  
2D Image Processing Library for Cortex-M Processors
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: 05. Sept 2022
26 * $Revision: V.1.0.7
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#elif defined(__IS_COMPILER_ARM_COMPILER_5__)
54# pragma diag_suppress 1296,174
55#endif
56
57/*!
58 * \addtogroup gKernel 1 Kernel
59 * @{
60 */
61
62/*============================ MACROS ========================================*/
63
64/* arm-2d version */
65#define ARM_2D_VERSION_MAJOR 1 //!< Major version
66#define ARM_2D_VERSION_MINOR 1 //!< Minor version
67#define ARM_2D_VERSION_PATCH 0 //!< Patch number
68#define ARM_2D_VERSION_STR "preview1" //!< tag
69
70/*!
71 * \brief arm-2d version number in decimal
72 *
73 */
74#define ARM_2D_VERISON ( ARM_2D_VERSION_MAJOR * 10000ul \
75 + ARM_2D_VERSION_MINOR * 100ul \
76 ARM_2D_VERSION_PATCH)
77
78/*============================ MACROFIED FUNCTIONS ===========================*/
79/*============================ TYPES =========================================*/
80
81/*!
82 * \brief a type for arm-2d runtime configuration
83 *
84 */
85typedef struct {
86 /*! if the target region is out of the target tile, return arm_fsm_rt_cpl */
87 uint8_t TREAT_OUT_OF_RANGE_AS_COMPLETE : 1;
88
89 /*! indicate that there is a dedicated thread to run arm_2d_task() in RTOS env */
90 uint8_t HAS_DEDICATED_THREAD_FOR_2D_TASK : 1;
91 uint8_t : 6;
92} arm_2d_runtime_feature_t;
93
94/*!
95 * \brief a type for arm-2d version
96 *
97 */
98typedef struct {
99 uint8_t Major; //!< major version
100 uint8_t Minor; //!< minor version
101 uint8_t Patch; //!< patch number
102 uint8_t : 8;
103} arm_2d_version_t;
104
105/*============================ GLOBAL VARIABLES ==============================*/
106
107/*!
108 * \brief arm-2d runtime feature configuration
109 *
110 */
111extern
112arm_2d_runtime_feature_t ARM_2D_RUNTIME_FEATURE;
113
114/*!
115 * \brief arm-2d version
116 *
117 */
118extern
119const arm_2d_version_t ARM_2D_VERSION;
120
121/*============================ PROTOTYPES ====================================*/
122
123/*!
124 * \brief initialise arm-2d
125 */
126extern
127void arm_2d_init(void);
128
129/*!
130 * \brief set the default frame buffer
131 * \param ptFrameBuffer the new frame buffer,
132 * \note Passing NULL means using no default framebuffer
133 * \return arm_2d_tile_t* the address of the old frame buffer
134 */
135extern
136arm_2d_tile_t *arm_2d_set_default_frame_buffer(
137 const arm_2d_tile_t *ptFrameBuffer);
138
139/*!
140 * \brief get the default frame buffer
141 * \return arm_2d_tile_t* the address of the default frame buffer
142 */
143extern
144arm_2d_tile_t *arm_2d_get_default_frame_buffer(void);
145
146/*!
147 * \brief attach a user param (which could be a pointer) to specified OP
148 *
149 * \param ptOP the address of the target OP (NULL means using the default OP)
150 *
151 * \param pUserParam a user parameter (it can be used as a pointer)
152 */
153extern
154void arm_2d_set_user_param(arm_2d_op_core_t *ptOP, uintptr_t pUserParam);
155
156/*!
157 * \brief wait asynchronous operation complete
158 * \param[in] ptOP the address of the target OP (NULL means using the default OP)
159 * \retval true sync up with operation
160 * \retval false operation is busy
161 */
162extern
163bool arm_2d_op_wait_async(arm_2d_op_core_t *ptOP);
164
165/*!
166 \brief get the status of a specified OP,
167 \details usually, it is used after calling arm_2d_op_wait_async().
168 E.g.
169 \code
170 //! wait for previous operation complete
171 do {
172 arm_2d_op_wait_async();
173 arm_2d_op_status_t tStatus = arm_2d_get_op_status();
174 if (tStatus.bIOError) {
175 //! error detected
176 ...
177 } else if (tStatus.bOpCpl) {
178 break;
179 }
180 } while(true);
181 \endcode
182 \param ptOP the address of the target OP (NULL means using the default OP)
183 \return arm_2d_op_status_t the operation status
184 */
185extern
186arm_2d_op_status_t arm_2d_get_op_status(arm_2d_op_core_t *ptOP);
187
188/*!
189 * \brief arm-2d pixel pipeline task entery
190 * \note This function is *TRHEAD-SAFE*
191 * \param ptTask the address of an arm-2d task control block
192 * \retval arm_fsm_rt_cpl The sub-task FIFO is empty, the caller can wait for a
193 * semaphore set by arm_2d_notif_sub_task_fifo_task_arrive()
194 * \retval arm_fsm_rt_on_going The arm_2d_task yields
195 * \retval arm_fsm_rt_async You shouldn't see this value
196 * \retval arm_fsm_rt_wait_for_obj hardware accelerator wants to sync-up with applications.
197 * \retval (<0) Serious error is detected.
198 */
199extern
200arm_fsm_rt_t arm_2d_task(arm_2d_task_t *ptTask);
201
202/*! @} */
203
204/*! \note delibrately comment out */
205//#if defined(__clang__)
206//# pragma clang diagnostic pop
207//#endif
208
209#ifdef __cplusplus
210}
211#endif
212
213
214#endif