1 /*
2  * Arm SCP/MCP Software
3  * Copyright (c) 2015-2022, Arm Limited and Contributors. All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  *
7  * Description:
8  *     Events.
9  */
10 
11 #ifndef FWK_EVENT_H
12 #define FWK_EVENT_H
13 
14 #include <internal/fwk_event.h>
15 
16 #include <fwk_align.h>
17 #include <fwk_id.h>
18 #include <fwk_list.h>
19 
20 #include <stdbool.h>
21 #include <stddef.h>
22 #include <stdint.h>
23 
24 /*!
25  * \addtogroup GroupLibFramework Framework
26  * \{
27  */
28 
29 /*!
30  * \defgroup GroupEvent Events
31  * \{
32  */
33 
34 /*!
35  * \brief Number of bytes available within each event definition for
36  *     event-specific parameters.
37  */
38 #define FWK_EVENT_PARAMETERS_SIZE 16
39 
40 /*!
41  * \brief Event.
42  *
43  * \details Events are used to facilitate event-based inter-process
44  *      communication between modules. Each event represents an asynchronous
45  *      message to one module from another, to which the target module can
46  *      respond if necessary.
47  */
48 struct fwk_event {
49     /*!
50      * \internal
51      * \brief Linked list node.
52      */
53     struct fwk_slist_node slist_node;
54 
55     /*! Identifier of the event source */
56     fwk_id_t source_id;
57 
58     /*! Identifier of the event target */
59     fwk_id_t target_id;
60 
61     /*!
62      *  Unique event number used to identify an event. The cookie is
63      *  automatically set by the framework.
64      */
65     uint32_t cookie;
66 
67     /*! Flag indicating whether the event is a response to another event */
68     bool is_response;
69 
70     /*! Flag indicating whether the event source expects a response */
71     bool response_requested;
72 
73     /*! Flag indicating whether the event is a notification */
74     bool is_notification;
75 
76     /*!
77      * \brief Flag indicating whether the event is a delayed response
78      */
79     bool is_delayed_response;
80 
81     /*!
82      * \brief Event identifier.
83      *
84      * \details Each module or element may define its own set of events. The
85      *      event identifier must therefore be interpreted in the context of its
86      *      target.
87      */
88     fwk_id_t id;
89 
90     /*! Table of event parameters */
91     alignas(max_align_t) uint8_t params[FWK_EVENT_PARAMETERS_SIZE];
92 };
93 
94 /*!
95  * \brief Light event.
96  *
97  * \details Light events are used only in cases where very little information
98  *      is needed by the target module and in a use case where creating and
99  *      initializing a <tt> struct fwk_event </tt> type object can affect
100  *      the performance of the use case(e.g. DVFS).
101  *      The framework copies the light event information in a pre-allocated
102  *      <tt> struct fwk_event </tt> type object before it starts processing
103  *      the event.
104  */
105 struct fwk_event_light {
106     /*! Identifier of the event source */
107     fwk_id_t source_id;
108 
109     /*! Identifier of the event target */
110     fwk_id_t target_id;
111 
112     /*!
113      * \brief Event identifier.
114      *
115      * \details Each module or element may define its own set of events. The
116      *      event identifier must therefore be interpreted in the context of its
117      *      target.
118      */
119     fwk_id_t id;
120 
121     /*! Flag indicating whether the event source expects a response */
122     bool response_requested;
123 };
124 
125 /*!
126  * \}
127  */
128 
129 /*!
130  * \}
131  */
132 
133 #endif /* FWK_EVENT_H */
134