Merge tag 'v5.15.57' into rpi-5.15.y
[platform/kernel/linux-rpi.git] / drivers / usb / host / dwc_common_port / dwc_notifier.h
1
2 #ifndef __DWC_NOTIFIER_H__
3 #define __DWC_NOTIFIER_H__
4
5 #ifdef __cplusplus
6 extern "C" {
7 #endif
8
9 #include "dwc_os.h"
10
11 /** @file
12  *
13  * A simple implementation of the Observer pattern.  Any "module" can
14  * register as an observer or notifier.  The notion of "module" is abstract and
15  * can mean anything used to identify either an observer or notifier.  Usually
16  * it will be a pointer to a data structure which contains some state, ie an
17  * object.
18  *
19  * Before any notifiers can be added, the global notification manager must be
20  * brought up with dwc_alloc_notification_manager().
21  * dwc_free_notification_manager() will bring it down and free all resources.
22  * These would typically be called upon module load and unload.  The
23  * notification manager is a single global instance that handles all registered
24  * observable modules and observers so this should be done only once.
25  *
26  * A module can be observable by using Notifications to publicize some general
27  * information about it's state or operation.  It does not care who listens, or
28  * even if anyone listens, or what they do with the information.  The observable
29  * modules do not need to know any information about it's observers or their
30  * interface, or their state or data.
31  *
32  * Any module can register to emit Notifications.  It should publish a list of
33  * notifications that it can emit and their behavior, such as when they will get
34  * triggered, and what information will be provided to the observer.  Then it
35  * should register itself as an observable module. See dwc_register_notifier().
36  *
37  * Any module can observe any observable, registered module, provided it has a
38  * handle to the other module and knows what notifications to observe.  See
39  * dwc_add_observer().
40  *
41  * A function of type dwc_notifier_callback_t is called whenever a notification
42  * is triggered with one or more observers observing it.  This function is
43  * called in it's own process so it may sleep or block if needed.  It is
44  * guaranteed to be called sometime after the notification has occurred and will
45  * be called once per each time the notification is triggered.  It will NOT be
46  * called in the same process context used to trigger the notification.
47  *
48  * @section Limitiations
49  *
50  * Keep in mind that Notifications that can be triggered in rapid sucession may
51  * schedule too many processes too handle.  Be aware of this limitation when
52  * designing to use notifications, and only add notifications for appropriate
53  * observable information.
54  *
55  * Also Notification callbacks are not synchronous.  If you need to synchronize
56  * the behavior between module/observer you must use other means.  And perhaps
57  * that will mean Notifications are not the proper solution.
58  */
59
60 struct dwc_notifier;
61 typedef struct dwc_notifier dwc_notifier_t;
62
63 /** The callback function must be of this type.
64  *
65  * @param object This is the object that is being observed.
66  * @param notification This is the notification that was triggered.
67  * @param observer This is the observer
68  * @param notification_data This is notification-specific data that the notifier
69  * has included in this notification.  The value of this should be published in
70  * the documentation of the observable module with the notifications.
71  * @param user_data This is any custom data that the observer provided when
72  * adding itself as an observer to the notification. */
73 typedef void (*dwc_notifier_callback_t)(void *object, char *notification, void *observer,
74                                         void *notification_data, void *user_data);
75
76 /** Brings up the notification manager. */
77 extern int dwc_alloc_notification_manager(void *mem_ctx, void *wkq_ctx);
78 /** Brings down the notification manager. */
79 extern void dwc_free_notification_manager(void);
80
81 /** This function registers an observable module.  A dwc_notifier_t object is
82  * returned to the observable module.  This is an opaque object that is used by
83  * the observable module to trigger notifications.  This object should only be
84  * accessible to functions that are authorized to trigger notifications for this
85  * module.  Observers do not need this object. */
86 extern dwc_notifier_t *dwc_register_notifier(void *mem_ctx, void *object);
87
88 /** This function unregisters an observable module.  All observers have to be
89  * removed prior to unregistration. */
90 extern void dwc_unregister_notifier(dwc_notifier_t *notifier);
91
92 /** Add a module as an observer to the observable module.  The observable module
93  * needs to have previously registered with the notification manager.
94  *
95  * @param observer The observer module
96  * @param object The module to observe
97  * @param notification The notification to observe
98  * @param callback The callback function to call
99  * @param user_data Any additional user data to pass into the callback function */
100 extern int dwc_add_observer(void *observer, void *object, char *notification,
101                             dwc_notifier_callback_t callback, void *user_data);
102
103 /** Removes the specified observer from all notifications that it is currently
104  * observing. */
105 extern int dwc_remove_observer(void *observer);
106
107 /** This function triggers a Notification.  It should be called by the
108  * observable module, or any module or library which the observable module
109  * allows to trigger notification on it's behalf.  Such as the dwc_cc_t.
110  *
111  * dwc_notify is a non-blocking function.  Callbacks are scheduled called in
112  * their own process context for each trigger.  Callbacks can be blocking.
113  * dwc_notify can be called from interrupt context if needed.
114  *
115  */
116 void dwc_notify(dwc_notifier_t *notifier, char *notification, void *notification_data);
117
118 #ifdef __cplusplus
119 }
120 #endif
121
122 #endif /* __DWC_NOTIFIER_H__ */