EM-ODP
3.7.0
Event Machine on ODP
Main Page
Related Pages
Modules
Data Structures
Data Structures
Data Structure Index
Data Fields
All
_
a
b
c
d
e
f
g
h
i
l
m
n
o
p
q
r
s
t
u
v
w
Variables
_
a
b
c
d
e
f
g
h
i
l
m
n
o
p
q
r
s
t
u
v
w
Files
File List
Globals
All
_
a
c
d
e
h
i
l
o
p
q
r
s
u
Functions
_
a
c
d
e
h
i
o
p
q
s
Variables
Typedefs
e
i
l
o
q
Enumerations
Enumerator
e
i
Macros
e
i
p
r
s
u
Examples
•
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Modules
Pages
event_machine.h
Go to the documentation of this file.
1
/*
2
* Copyright (c) 2012, Nokia Siemens Networks
3
* Copyright (c) 2015-2024, Nokia Solutions and Networks
4
* All rights reserved.
5
*
6
* Redistribution and use in source and binary forms, with or without
7
* modification, are permitted provided that the following conditions
8
* are met:
9
*
10
* * Redistributions of source code must retain the above copyright
11
* notice, this list of conditions and the following disclaimer.
12
* * Redistributions in binary form must reproduce the above copyright
13
* notice, this list of conditions and the following disclaimer in the
14
* documentation and/or other materials provided with the distribution.
15
* * Neither the name of the copyright holder nor the names of its
16
* contributors may be used to endorse or promote products derived
17
* from this software without specific prior written permission.
18
*
19
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
*/
31
32
#ifndef EVENT_MACHINE_H
33
#define EVENT_MACHINE_H
34
35
#pragma GCC visibility push(default)
36
37
/**
38
* @file
39
* Event Machine API
40
*
41
* This file includes all other needed EM headers
42
*/
43
44
#ifdef __cplusplus
45
extern
"C"
{
46
#endif
47
48
/** @mainpage
49
*
50
* @section section_1 General
51
* Event Machine (EM) is a framework and an architectural abstraction of an
52
* event driven, multicore optimized, processing concept originally developed
53
* for the networking data plane. It offers an easy programming concept for
54
* scalable and dynamically load balanced multicore applications with a very
55
* low overhead run-to-completion principle.
56
*
57
* Events, queues and execution objects (EO) along with the scheduler and the
58
* dispatcher form the main elements of the EM concept. An event is an
59
* application specific piece of data (like a message or a network packet)
60
* describing work, something to do. All processing in EM must be triggered by
61
* an event. Events are sent to asynchronous application specific EM queues.
62
* A dispatcher loop is run by a single thread on each core in the EM instance
63
* ("core" is used here to refer to a core or one HW thread on multi-threaded
64
* cores). The dispatcher on each core interfaces with the scheduler and asks
65
* for an event to process. The scheduler then evaluates the state of all the
66
* EM queues and gives the highest priority event available to the requesting
67
* dispatcher. The dispatcher looks up which EO owns the queue that the event
68
* came from and finally calls the EO's registered receive function to deliver
69
* the event for processing. When the event has been handled and the EO's
70
* receive function returns, it's again time for the dispatcher on that core to
71
* request another event from the scheduler and deliver it to the corresponding
72
* EO. The aforedescribed scenario happens in parallel on all cores running the
73
* EM instance. Events originating from a particular queue might thus be given
74
* for processing on any core, decided separately for each event by the
75
* scheduler as the dispatcher on a core requests more work - this is per-event
76
* dynamic load-balancing. EM contains mechanisms to ensure atomicity and event
77
* (re-)ordering.
78
*
79
* The EM concept has been designed to be highly efficient, operating in a
80
* run-to-completion manner on each participating core with neither context
81
* switching nor pre-emption slowing down the event processing loops.
82
* EM can run on bare metal for best performance or under an operating system
83
* with special arrangements (e.g. one thread per core with thread affinity).
84
*
85
* The concept and the API are intended to allow fairly easy implementations on
86
* general purpose or networking oriented multicore packet processing SoCs,
87
* which typically also contain accelerators for packet processing needs.
88
* Efficient integration with modern HW accelerators has been a major driver of
89
* the EM concept.
90
*
91
* One general principle of the EM API is that the function calls are mostly
92
* multicore safe. The application still needs to consider parallel processing
93
* data hazards and race conditions unless explicitly documented in the API for
94
* the function call in question. For example, one core might ask for a queue
95
* context while another core changes it, thus the returned context may be
96
* invalid (valid data, but either the old or the new value is returned). Thus
97
* modifications of shared state or data should be protected by an atomic
98
* context (if load balancing is used) or otherwise synchronized by the
99
* application itself. One simple way to achieve atomic processing is to use an
100
* atomic queue to serialize the EO's incoming events and perform management
101
* operations in the EO's receive function. This serialization limits the
102
* throughput of the atomic queue in question to the equivalent throughput of a
103
* single core, but since normally EM applications use multiple queues, all
104
* cores should get events to process and the total throughput will be relative
105
* to the number of cores running the EM instance.
106
*
107
* EM_64_BIT or EM_32_BIT (needs to be defined by the build) defines whether
108
* (most of) the types used in the API are 32 or 64 bits wide. NOTE, that this
109
* is a major decision, since it may limit value passing between different
110
* systems using the defined types directly. Using 64-bits may allow for a more
111
* efficient underlying implementation, as e.g. more data can be coded in
112
* 64-bit identifiers.
113
*
114
* @section section_2 Principles
115
* - This API attempts to guide towards a portable application architecture,
116
* but is not defined for portability by re-compilation. Many things are system
117
* specific giving more possibilities for efficient use of HW resources.
118
* - EM does not define event content (one exception, see em_alloc()). This is
119
* a choice made for performance reasons, since most HW devices use proprietary
120
* descriptors. This API enables the usage of those directly.
121
* - EM does not define a detailed queue scheduling discipline or an API to set
122
* it up with (or actually anything to configure a system). The priority value
123
* in this API is a (mapped) system specific QoS class label only.
124
* - In general, EM does not implement a full SW platform or a middleware
125
* solution, it implements a subset - a driver level part. For best
126
* performance it can be used directly from the applications.
127
*
128
* @section section_3 Inter-system communication
129
* EM does not define how to communicate with another EM instance or another
130
* system transparently. However, this is a typical need and the current API
131
* does have ways to achieve almost transparent communication between systems
132
* ("event chaining"):
133
* Since the queue identifier is a system specific value, it is easy to encode
134
* extra information into it in the EM implementation. For instance it could be
135
* split into two parts, where the lower part is a local queue id or index and
136
* the higher part, if not zero, points to another system. The implementation
137
* of em_send() can detect a non-local queue and forward events to the target
138
* using any transport mechanism available and once at the target instance the
139
* lower part is used to map to a local queue. For the application nothing
140
* changes. The problem is the lack of shared memory between those systems.
141
* The given event can be fully copied, but it should not have any references to
142
* sender's local memory. Thus it is not fully transparent if the event contains
143
* references to local memory (e.g. pointers).
144
*
145
* @section section_4 Files
146
* @subsection sub_1 Generic
147
* - event_machine.h
148
* - Event Machine API
149
* The application should include this file only.
150
*
151
* Files included by event_machine.h:
152
* - event_machine_version.h
153
* - Event Machine version defines, macros and APIs
154
* - event_machine_deprecated.h
155
* - EM API deprecation defines & macros
156
* - event_machine_types.h
157
* - Event Machine basic types
158
* - event_machine_event.h
159
* - event related functionality
160
* - event_machine_packet.h
161
* - packet event related functionality
162
* - event_machine_eo.h
163
* - EO related functionality
164
* - event_machine_event_group.h
165
* - event group feature for fork-join type of operations using events
166
* - event_machine_atomic_group.h
167
* - functionality for atomic groups of queues (API 1.1)
168
* - event_machine_queue.h
169
* - queue related functionality
170
* - event_machine_queue_group.h
171
* - queue group related functionality
172
* - event_machine_error.h
173
* - error management related functionality
174
* - event_machine_core.h
175
* - core/thread related functionality
176
* - event_machine_scheduler.h
177
* - scheduling related functionality
178
* - event_machine_dispatcher.h
179
* - dispatching related functionality
180
* - event_machine_timer.h
181
* - timer APIs
182
*
183
* @subsection sub_2 Platform Specific
184
* (also included by event_machine.h)
185
* - event_machine_config.h
186
* - Event Machine constants and configuration options
187
* - event_machine_hw_config.h
188
* - HW specific constants and configuration options
189
* - event_machine_hw_specific.h
190
* - HW specific functions and macros
191
* - event_machine_hw_types.h
192
* - HW specific types
193
* - event_machine_hooks.h
194
* - API-hooks and idle-hooks
195
* - event_machine_init.h
196
* - Event Machine initialization
197
* - event_machine_pool.h
198
* - event pool related functionality
199
* - event_machine_timer_hw_specific.h
200
* - Platform specific timer definitions
201
*
202
* @subsection sub_3 Helper
203
* These files must be separately included by the application on a need basis.
204
* - event_machine_helper.h
205
* - optional helper routines
206
* - event_machine_debug.h
207
* - optional debug helpers (only for debug use)
208
*
209
* @subsection sub_4 Extensions
210
* These files must be separately included by the application on a need basis.
211
* - event_machine_odp_ext.h
212
* - EM <-> ODP conversion functions and ODP related helpers
213
*
214
* @example hello.c
215
* @example api_hooks.c
216
* @example dispatcher_callback.c
217
* @example error.c
218
* @example event_group.c
219
* @example event_group_abort.c
220
* @example event_group_assign_end.c
221
* @example event_group_chaining.c
222
* @example fractal.c
223
* @example ordered.c
224
* @example queue_types_ag.c
225
* @example queue_types_local.c
226
* @example queue_group.c
227
* @example timer_hello.c
228
* performance:
229
* @example atomic_processing_end.c
230
* @example loop.c
231
* @example loop_multircv.c
232
* @example loop_refs.c
233
* @example loop_vectors.c
234
* @example pairs.c
235
* @example pool_perf.c
236
* @example queue_groups.c
237
* @example queues.c
238
* @example queues_local.c
239
* @example queues_output.c
240
* @example queues_unscheduled.c
241
* @example scheduling_latency.c
242
* @example send_multi.c
243
* @example timer_test.c
244
* @example timer_test_periodic.c
245
* @example timer_test_ring.c
246
* bench:
247
* @example bench_event.c
248
* @example bench_pool.c
249
*/
250
251
/* EM deprecated */
252
#include <
event_machine/api/event_machine_deprecated.h
>
253
254
/* EM version */
255
#include <
event_machine/api/event_machine_version.h
>
256
257
/* EM config & types */
258
#include <
event_machine/platform/event_machine_config.h
>
259
#include <
event_machine/api/event_machine_types.h
>
260
261
/* HW specific EM config & types */
262
#include <
event_machine/platform/event_machine_hw_config.h
>
263
#include <
event_machine/platform/event_machine_hw_types.h
>
264
265
/* EM error management */
266
#include <
event_machine/api/event_machine_error.h
>
267
/* EM Execution Object (EO) related functions */
268
#include <
event_machine/api/event_machine_eo.h
>
269
/* EM Queue functions */
270
#include <
event_machine/api/event_machine_queue.h
>
271
/* EM Queue Group functions */
272
#include <
event_machine/api/event_machine_queue_group.h
>
273
/* EM Core functions*/
274
#include <
event_machine/api/event_machine_core.h
>
275
/* EM Event functions */
276
#include <
event_machine/api/event_machine_event.h
>
277
/* EM Packet Event functions */
278
#include <
event_machine/api/event_machine_packet.h
>
279
/* EM Atomic Group functions */
280
#include <
event_machine/api/event_machine_atomic_group.h
>
281
/* EM Event Group functions */
282
#include <
event_machine/api/event_machine_event_group.h
>
283
/* EM Scheduler functions */
284
#include <
event_machine/api/event_machine_scheduler.h
>
285
/* EM Dispatcher functions */
286
#include <
event_machine/api/event_machine_dispatcher.h
>
287
288
/* EM Event Pool functions */
289
#include <
event_machine/platform/event_machine_pool.h
>
290
/* EM API hooks */
291
#include <
event_machine/platform/event_machine_hooks.h
>
292
/* EM initialization and termination */
293
#include <
event_machine/platform/event_machine_init.h
>
294
/* Other HW/Platform specific functions */
295
#include <
event_machine/platform/event_machine_hw_specific.h
>
296
/* EM Timer HW/Platform specific */
297
#include <
event_machine/platform/event_machine_timer_hw_specific.h
>
298
/* EM Timer */
299
#include <
event_machine/api/event_machine_timer.h
>
300
301
#ifdef __cplusplus
302
}
303
#endif
304
305
#pragma GCC visibility pop
306
#endif
/* EVENT_MACHINE_H */
event_machine_queue_group.h
event_machine_hw_specific.h
event_machine_scheduler.h
event_machine_version.h
event_machine_queue.h
event_machine_timer.h
event_machine_atomic_group.h
event_machine_dispatcher.h
event_machine_config.h
event_machine_error.h
event_machine_event.h
event_machine_pool.h
event_machine_deprecated.h
event_machine_packet.h
event_machine_event_group.h
event_machine_hooks.h
event_machine_hw_types.h
event_machine_hw_config.h
event_machine_types.h
event_machine_init.h
event_machine_timer_hw_specific.h
event_machine_core.h
event_machine_eo.h