From cf3a7d16049346b0f329daa75d850bfc04dce7fb Mon Sep 17 00:00:00 2001 From: Marc Herbert Date: Tue, 29 Jun 2021 05:34:07 +0000 Subject: [PATCH] notifier.h: document the API ... and rename some parameter names. Signed-off-by: Marc Herbert --- src/include/sof/lib/notifier.h | 40 +++++++++++++++++++++++++++++----- 1 file changed, 34 insertions(+), 6 deletions(-) diff --git a/src/include/sof/lib/notifier.h b/src/include/sof/lib/notifier.h index 6c00a89b4..2f10b2d97 100644 --- a/src/include/sof/lib/notifier.h +++ b/src/include/sof/lib/notifier.h @@ -58,15 +58,43 @@ struct notify_data { struct notify **arch_notify_get(void); -int notifier_register(void *receiver, void *caller, enum notify_id type, - void (*cb)(void *arg, enum notify_id type, void *data), +/** Register a callback to be run when event 'type' happens. + * + * The identifier for un-registration is the tuple (receiver_data, + * caller_id_filter, event_type), the callback argument is not part of + * it. + * + * caller_data argument from notifier_event() + * + * @param receiver_data private data passed to the callback. + * @param caller_id_filter optional, can be used to be notified only by + * some specific notifier_event() calls when not NULL. + * @param event_type list of callbacks to be added to + * @param callback callback function + * @param flags see NOTIFIER_FLAG_* above + */ +int notifier_register(void *receiver_data, void *caller_id_filter, enum notify_id event_type, + void (*callback)(void *receiver_data, enum notify_id event_type, + void *caller_data), uint32_t flags); -void notifier_unregister(void *receiver, void *caller, enum notify_id type); -void notifier_unregister_all(void *receiver, void *caller); + +/** Unregister all callbacks matching that arguments tuple. NULL acts + * as a wildcard. + */ +void notifier_unregister(void *receiver_data_filter, void *caller_id_filter, enum notify_id type); + +/** Unregister callbacks matching the arguments for every notify_id. + * A NULL parameter acts as a wildcard. + */ +void notifier_unregister_all(void *receiver_data_filter, void *caller_id_filter); void notifier_notify_remote(void); -void notifier_event(const void *caller, enum notify_id type, uint32_t core_mask, - void *data, uint32_t data_size); + +/* data_size is required to manage cache coherency for notifications + * across cores. + */ +void notifier_event(const void *caller_id, enum notify_id event_type, uint32_t core_mask, + void *caller_data, uint32_t data_size); void init_system_notify(struct sof *sof);