EM-ODP  3.7.0
Event Machine on ODP
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 */
253 
254 /* EM version */
256 
257 /* EM config & types */
260 
261 /* HW specific EM config & types */
264 
265 /* EM error management */
267 /* EM Execution Object (EO) related functions */
269 /* EM Queue functions */
271 /* EM Queue Group functions */
273 /* EM Core functions*/
275 /* EM Event functions */
277 /* EM Packet Event functions */
279 /* EM Atomic Group functions */
281 /* EM Event Group functions */
283 /* EM Scheduler functions */
285 /* EM Dispatcher functions */
287 
288 /* EM Event Pool functions */
290 /* EM API hooks */
292 /* EM initialization and termination */
294 /* Other HW/Platform specific functions */
296 /* EM Timer HW/Platform specific */
298 /* EM Timer */
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