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
230
231
232
233
|
/* Copyright (c) 2013, Linaro Limited
* All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
/**
* @file
*
* ODP initialization.
* ODP requires a global level init for the process and a local init per
* thread before the other ODP APIs may be called.
* - odp_init_global()
* - odp_init_local()
*
* For a graceful termination the matching termination APIs exit
* - odp_term_global()
* - odp_term_local()
*/
#ifndef ODP_API_INIT_H_
#define ODP_API_INIT_H_
#ifdef __cplusplus
extern "C" {
#endif
#include <odp/std_types.h>
#include <odp/hints.h>
#include <odp/thread.h>
/** @defgroup odp_initialization ODP INITIALIZATION
* Initialisation operations.
* @{
*/
/**
* ODP log level.
*/
typedef enum odp_log_level {
ODP_LOG_DBG,
ODP_LOG_ERR,
ODP_LOG_UNIMPLEMENTED,
ODP_LOG_ABORT,
ODP_LOG_PRINT
} odp_log_level_e;
/**
* ODP log function
*
* Instead of direct prints to stdout/stderr all logging in an ODP
* implementation should be done via this function or its wrappers.
*
* The application can provide this function to the ODP implementation in two
* ways:
*
* - A callback passed in via in odp_init_t and odp_init_global()
* - By overriding the ODP implementation default log function
* odp_override_log().
*
* @warning The latter option is less portable and GNU linker dependent
* (utilizes function attribute "weak"). If both are defined, the odp_init_t
* function pointer has priority over the override function.
*
* @param level Log level
* @param fmt printf-style message format
*
* @return The number of characters logged on success
* @retval <0 on failure
*/
int odp_override_log(odp_log_level_e level, const char *fmt, ...);
/**
* ODP abort function
*
* Instead of directly calling abort, all abort calls in the implementation
* should be done via this function or its wrappers.
*
* The application can provide this function to the ODP implementation in two
* ways:
*
* - A callback passed in via odp_init_t and odp_init_global()
* - By overriding the ODP implementation default abort function
* odp_override_abort().
*
* @warning The latter option is less portable and GNU linker dependent
* (utilizes function attribute "weak"). If both are defined, the odp_init_t
* function pointer has priority over the override function.
*
* @warning this function shall not return
*/
void odp_override_abort(void) ODP_NORETURN;
/** Replaceable logging function */
typedef int (*odp_log_func_t)(odp_log_level_e level, const char *fmt, ...);
/** Replaceable abort function */
typedef void (*odp_abort_func_t)(void) ODP_NORETURN;
/**
* ODP initialization data
*
* Data that is required to initialize the ODP API with the
* application specific data such as specifying a logging callback, the log
* level etc.
*
* @note It is expected that all unassigned members are zero
*/
typedef struct odp_init_t {
/** Maximum number of worker threads the user will run concurrently.
Valid range is from 0 to platform specific maximum. Set both
num_worker and num_control to zero for default number of threads. */
int num_worker;
/** Maximum number of control threads the user will run concurrently.
Valid range is from 0 to platform specific maximum. Set both
num_worker and num_control to zero for default number of threads. */
int num_control;
/** Replacement for the default log fn */
odp_log_func_t log_fn;
/** Replacement for the default abort fn */
odp_abort_func_t abort_fn;
} odp_init_t;
/**
* ODP platform initialization data
*
* @note ODP API does nothing with this data. It is the underlying
* implementation that requires it and any data passed here is not portable.
* It is required that the application takes care of identifying and
* passing any required platform specific data.
*/
typedef struct odp_platform_init_t {
} odp_platform_init_t;
/**
* Global ODP initialization
*
* This function must be called once before calling any other ODP API
* functions.
*
* @param params Those parameters that are interpreted by the ODP API.
* Use NULL to set all parameters to their defaults.
* @param platform_params Those parameters that are passed without
* interpretation by the ODP API to the implementation.
* Use NULL to set all parameters to their defaults.
* @retval 0 on success
* @retval <0 on failure
*
* @see odp_term_global()
* @see odp_init_local() which is required per thread before use.
*/
int odp_init_global(const odp_init_t *params,
const odp_platform_init_t *platform_params);
/**
* Global ODP termination
*
* This function is the final ODP call made when terminating
* an ODP application in a controlled way. It cannot handle exceptional
* circumstances. In general it calls the API modules terminate functions in
* the reverse order to that which the module init functions were called
* during odp_init_global().
*
* @retval 0 on success
* @retval <0 on failure
*
* @note This function should be called by the last ODP thread. To simplify
* synchronization between threads odp_term_local() indicates by its return
* value if it was the last thread.
*
* @warning The unwinding of HW resources to allow them to be reused without
* reseting the device is a complex task that the application is expected to
* coordinate. This api may have platform dependent implications.
*
* @see odp_init_global()
* @see odp_term_local() which must have been called prior to this.
*/
int odp_term_global(void);
/**
* Thread local ODP initialization
*
* All threads must call this function before calling any other ODP API
* functions.
*
* @param thr_type Thread type
*
* @param thr_type Thread type
*
* @retval 0 on success
* @retval <0 on failure
*
* @see odp_term_local()
* @see odp_init_global() which must have been called prior to this.
*/
int odp_init_local(odp_thread_type_t thr_type);
/**
* Thread local ODP termination
*
* This function is the second to final ODP call made when terminating
* an ODP application in a controlled way. It cannot handle exceptional
* circumstances. In general it calls the API modules per thread terminate
* functions in the reverse order to that which the module init functions were
* called during odp_init_local().
*
* @retval 1 on success and more ODP threads exist
* @retval 0 on success and this is the last ODP thread
* @retval <0 on failure
*
* @warning The unwinding of HW resources to allow them to be reused without
* reseting the device is a complex task that the application is expected
* to coordinate.
*
* @see odp_init_local()
* @see odp_term_global() should be called by the last ODP thread before exit
* of an application.
*/
int odp_term_local(void);
/**
* @}
*/
#ifdef __cplusplus
}
#endif
#endif
|
