1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
/*
* Copyright (C) 2015 - 2017 Intel Corporation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef _IA_IPF_TYPES_H_
#define _IA_IPF_TYPES_H_
/** @file ia_ipf_types.h
* This file contains data types for the Imaging Pipeline Framework (IPF).
* This framework provides functions to construct and execute pipelines
* consisting of so-called engines. Each pipeline stage executes one such
* engine.
* The engine structure defined in this file contains the interface that all
* IPF compatible engines need to implement.
* Each engine is expected to implement its own function to create an instance
* of such an engine.
*/
#include <stdint.h>
#include <stdbool.h>
#include "ia_types.h"
#ifdef __cplusplus
extern "C" {
#endif
/** The following macros define ranges for each of the IA imaging
* library's built-in IPF compatible modules. Each module
* will define its own buffer type identifiers for its own data
* types that are used for input, output or temporary (internal)
* buffers.
*/
#define IA_IPF_BUFFER_TYPES 0x00001000
#define IA_CP_BUFFER_TYPES 0x00002000
#define IA_FACE_BUFFER_TYPES 0x00003000
#define IA_REDEYE_BUFFER_TYPES 0x00004000
#define IA_ISP_BUFFER_TYPES 0x00005000
/** Externally defined engines can define their own buffer
* types starting at this number. */
#define IA_CUSTOM_BUFFER_TYPES 0x00100000
/**
* Define specific buffer types below
*/
#define IA_IPF_BUFFER_TYPE_FRAME (IA_IPF_BUFFER_TYPES + 0)
#define IA_IPF_BUFFER_TYPE_INT32 (IA_IPF_BUFFER_TYPES + 1)
#define IA_FACE_BUFFER_TYPE_FACE_LIST (IA_FACE_BUFFER_TYPES + 0)
typedef struct ia_ipf_buffer_container_t ia_ipf_buffer_container;
typedef struct ia_ipf_buffer_container_descr_t ia_ipf_buffer_container_descr;
/** Container type.
* This enum contains possible types of containers.
* Containers can either be a buffer or a buffer list.
*/
typedef enum {
ia_ipf_container_type_buffer,
ia_ipf_container_type_buffer_list,
}ia_ipf_container_type;
/** Buffer owner.
* This enum contains possible owners of buffers.
* Ownership is defined as the module that allocated the buffer.
* This means that the owner of the buffer is responsible for freeing
* the memory.
*/
typedef enum {
ia_ipf_buffer_owner_user, /**< Buffer is owned by the user of the IPF API */
ia_ipf_buffer_owner_framework, /**< Buffer is owned by the IPF implementation */
ia_ipf_buffer_owner_engine, /**< Buffer is owned by the firmware engine */
} ia_ipf_buffer_owner;
/** Compute resources.
* This is used in a number of places where we need to know whether code runs
* on a particular resource.
*/
typedef enum {
ia_ipf_resource_isp, /**< The ISP is the compute resource */
ia_ipf_resource_cpu, /**< The CPU is the compute resource */
ia_ipf_resource_num_resources,
} ia_ipf_resource;
/** IPF Buffer Descriptor.
* This structure describes various data buffers (for e.g. image frame) used by the IPF.
*/
typedef struct {
int32_t type; /**< Data type, module or user defined number */
ia_ipf_buffer_owner owner; /**< Indicator of the buffer owner. */
int32_t data_size; /**<< Size, in bytes, of the memory */
void *header;
int32_t header_size;
} ia_ipf_buffer_descr;
/** IPF Buffer Descriptor List
* This structure contains a list of buffer descriptors.
*/
typedef struct {
ia_ipf_buffer_container_descr *container_descrs;
int32_t num_container_descrs;
} ia_ipf_buffer_descr_list;
/** IPF Buffer.
* This structure contains an individual buffer
*/
typedef struct {
void *data; /**< Data pointer to raw pixel data */
} ia_ipf_buffer;
/** IPF Buffer list.
* This structure contains a list of buffers.
*/
typedef struct {
ia_ipf_buffer_container *buffer_containers; /**< Array of buffer containers */
int32_t num_buffers; /**< Number of buffers in the array */
} ia_ipf_buffer_list;
/** IPF Buffer Container Descriptor List.
* This structure describes the buffer container descriptor used in the IPF framework.
*/
struct ia_ipf_buffer_container_descr_t{
ia_ipf_container_type container_type; /**<< container type */
union {
ia_ipf_buffer_descr buffer_descr;
ia_ipf_buffer_descr_list buffer_descr_list;
}container; /**<< container descriptor */
};
/** IPF Buffer Container.
* This structure describes the buffer container used in the IPF framework.
*/
struct ia_ipf_buffer_container_t{
ia_ipf_buffer_container_descr container_descr; /**<< container descriptor */
union {
ia_ipf_buffer *buffer;
ia_ipf_buffer_list *buffer_list;
}container; /**<< container that holds a buffer or buffer list */
};
/** IPF Engine structure.
* This is the structure that each engine is required to implement in order to
* be compatbile with the IPF framework.
* Each engine is responsible for providing a function to create such an
* engine.
* Note that this describes an instance of an engine and each engine can be
* instantiated multiple times.
* Engines are free to allocate more memory than the size of this structure to
* hold internal state. This is why the destroy function in this structure
* must always be used to free the allocated memory; do not free this structure
* yourself.
*/
typedef struct ia_ipf_engine_t {
const char *isp_fw_file;
/**< Filename of the ISP firmware file. This will be NULL for non-ISP
engines. This filename should not include a path. */
const char *isp_fw_directory;
/**< Directory that contains the FW file. Built-in engines will have
this set to NULL in which case the IPF FW directory will be used.
Custom engines should specify the path themselves. */
ia_err (*init)(struct ia_ipf_engine_t *me,
const ia_ipf_buffer_list *input_buffers,
ia_ipf_buffer_descr_list **output_buffer_descrs_list,
ia_ipf_buffer_descr_list **temp_buffer_descrs_list,
int32_t load[ia_ipf_resource_num_resources]);
/**< Initialization function. This initializes this engine instance with
a set of input parameters (buffers). This function will fill in the
output_buffer_descrs_list, load and if the engine runs on the ISP,
the temp_buffers_descrs_list should also be filled in. The engine
framework will use this information to allocate all necessary
buffers. */
ia_err (*isp_preprocess)(struct ia_ipf_engine_t *me,
const ia_ipf_buffer_list *input_buffers,
const ia_ipf_buffer_list *output_buffers,
ia_ipf_buffer_list *temp_buffers);
/**< Pre-process arguments for ISP binary. ISP engines will fill
in this function pointer. CPU engines will set this to NULL.
This will convert input and output buffer pointers into the ISP
internal format which is stored in temp_buffers.
ISP engines need to implement this function because only the
temp_buffers are passed as arguments to the ISP FW. */
ia_err (*isp_postprocess)(struct ia_ipf_engine_t *me,
const ia_ipf_buffer_list *input_buffers,
ia_ipf_buffer_list *output_buffers,
const ia_ipf_buffer_list *temp_buffers);
/**< Post-process the ISP FW output, this step is optional.
When implemented, this function will peform some type of
post-processing on the ISP output before the CPU can use this
output data. */
ia_err (*execute)(struct ia_ipf_engine_t *me,
const ia_ipf_buffer_list *input_buffers,
ia_ipf_buffer_list *output_buffers,
ia_ipf_buffer_list *temp_buffers);
/**< Execute a CPU-only engine. ISP engines will be executed by the
framework implementation using the acceleration API; ISP
engines should set this pointer to NULL. */
ia_err (*cancel)(struct ia_ipf_engine_t *me,
ia_ipf_buffer_list *info);
/**< Cancel a CPU-only engine if it's currently running. If the
engine is not running when this function is called, this will
be a no-op. */
void (*destroy)(struct ia_ipf_engine_t *me);
/**< Destroy this engine instance. This will free any engine-owned
internal state as well as this structure. */
} ia_ipf_engine;
#ifdef __cplusplus
}
#endif
#endif /* _IA_IPF_TYPES_H_ */
|
