release/src-rt-6.x.4708/include/bcm_notif_pub.h

   1 /*
   2  * Public header file for event-component data structure and API
   3  *
   4  * This library provides a data structure and behavior for registering
   5  * interest in events and getting callbacks. The fundamental data structure
   6  * is an opaque type that servers instantiate. Servers then use function calls
   7  * to let clients express interest and register callback function pointers.
   8  * Servers can signal events and provide server-specific data on the event.
   9  *
  10  * The library guarantees that client callbacks occur in the same order that the
  11  * clients registered interest.
  12  *
  13  * Copyright (C) 2012, Broadcom Corporation
  14  * All Rights Reserved.
  15  *
  16  * This is UNPUBLISHED PROPRIETARY SOURCE CODE of Broadcom Corporation;
  17  * the contents of this file may not be disclosed to third parties, copied
  18  * or duplicated in any form, in whole or in part, without the prior
  19  * written permission of Broadcom Corporation.
  20  *
  21  * $Id$
  22  */
  23
  24 #ifndef BCM_NOTIF_PUB_H
  25 #define BCM_NOTIF_PUB_H 1
  26
  27 #include <osl.h>
  28 #include <bcm_mpool_pub.h>
  29
  30
  31 /*
  32 *****************************************************************************
  33 * Opaque type definitions for Event components.
  34 *****************************************************************************
  35 */
  36
  37 /*
  38  * The opaque type for global notifier state.
  39  */
  40 typedef struct bcm_notif_module bcm_notif_module_t;
  41
  42
  43 /*
  44  * The opaque type for a list of interested clients of an event.
  45  * This is incorporated and leveraged by a server.
  46  */
  47 struct bcm_notif_list_struct;
  48 typedef struct bcm_notif_list_struct *bcm_notif_h;
  49
  50 /*
  51  * Client data passed through during an event.
  52  * It's submitted by client to server at registration, and returned
  53  * from server to client upon notification. May be NULL if not needed.
  54  */
  55 typedef void * bcm_notif_client_data;
  56
  57 /*
  58  * Server data passed to client upon an event.
  59  * Actual format is server-specific and must be cast at runtime.
  60  */
  61 typedef void * bcm_notif_server_data;
  62
  63 /*
  64  * Type definition for a client callback routine.
  65  */
  66 typedef void (*bcm_notif_client_callback)(bcm_notif_client_data, bcm_notif_server_data);
  67
  68
  69 /*
  70 **************************************************
  71 * Function prototypes: operations on an event_list.
  72 **************************************************
  73 */
  74
  75 /*
  76  * bcm_notif_attach()
  77  *
  78  * Notifier module attach-time initialization.
  79  *
  80  * Parameters:
  81  *    osh                Operating system handle.
  82  *    mpm                Memory pool manager handle.
  83  *    max_notif_servers  Maximum number of supported servers.
  84  *    max_notif_clients  Maximum number of supported clients.
  85  * Returns:
  86  *    Global notifier module object. NULL on error.
  87  */
  88 bcm_notif_module_t* bcm_notif_attach(osl_t *osh,
  89                                      bcm_mpm_mgr_h mpm,
  90                                      int max_notif_servers,
  91                                      int max_notif_client);
  92
  93 /*
  94  * bcm_notif_detach()
  95  *
  96  * Notifier module detach-time deinitialization.
  97  *
  98  * Parameters:
  99  *    notif_module  Global notifier module object.
 100  * Returns:
 101  *    Nothing.
 102  */
 103 void bcm_notif_detach(bcm_notif_module_t *notif_module);
 104
 105 /*
 106  * bcm_notif_create_list()
 107  *
 108  * Initialize new list. Allocates memory.
 109  *
 110  * Parameters:
 111  *    notif_module  Global notifier module object.
 112  *    hdlp       Pointer to opaque list handle.
 113  * Returns:
 114  *    BCME_OK     Object initialized successfully. May be used.
 115  *    BCME_NOMEM  Initialization failed due to no memory. Object must not be used
 116  */
 117 int bcm_notif_create_list(bcm_notif_module_t *notif_module, bcm_notif_h *hdlp);
 118
 119 /*
 120  * bcm_notif_add_interest()
 121  *
 122  * Add an interested client
 123  *
 124  * Parameters
 125  *    list       Interest list to which the client is added
 126  *    hdl        Opaque list handle.
 127  *    callback   Client callback routine
 128  *    passthru   Client pass-thru data
 129  * Returns:
 130  *    BCME_OK     Client interest added successfully
 131  *    BCME_NOMEM  Add failed due to no memory.
 132  *
 133  */
 134 int bcm_notif_add_interest(bcm_notif_h hdl,
 135                            bcm_notif_client_callback callback,
 136                            bcm_notif_client_data passthru);
 137
 138 /*
 139  * bcm_notif_remove_interest()
 140  *
 141  * Remove an interested client. The callback and passthru must be identical to the data
 142  * supplied during registration.
 143  *
 144  * Parameters
 145  *    hdl        Opaque list handle.
 146  *    callback   Client callback routine
 147  *    passthru   Client pass-thru data
 148  * Returns:
 149  *    BCME_OK     Client interest added successfully
 150  *    BCME_ERROR  Failed for generic reason.
 151  *
 152  */
 153 int bcm_notif_remove_interest(bcm_notif_h hdl,
 154                               bcm_notif_client_callback callback,
 155                               bcm_notif_client_data passthru);
 156
 157
 158 /*
 159  * bcm_notif_signal()
 160  *
 161  * Notify all clients on an event list that the event has occured. Invoke their callbacks
 162  * and provide both the server data and the client passthru data.
 163  *
 164  * It is guaranteed that clients will be signaled in the same order in which they
 165  * expressed interest.
 166  *
 167  * Parameters
 168  *    hdl         Opaque list handle.
 169  *    server_data Server data for the notification
 170  * Returns:
 171  *    BCME_OK        Client interest added successfully
 172  *    BCME_NOTFOUND  Could not locate this specific client registration for removal.
 173  */
 174 int bcm_notif_signal(bcm_notif_h listp, bcm_notif_server_data data);
 175
 176 /*
 177  * bcm_notif_delete_list()
 178  *
 179  * Destroy a list. Free all the elements as well as the list itself.
 180  * After this call, the list must be reinitialized before it can be used.
 181  *
 182  * Parameters
 183  *    hdlp       Pointer to opaque list handle.
 184  * Returns:
 185  *    BCME_OK     Event list successfully deleted.
 186  *    BCME_ERROR  General error
 187  */
 188 int bcm_notif_delete_list(bcm_notif_h *hdlp);
 189
 190 /*
 191  * bcm_notif_dump_list()
 192  *
 193  * For debugging, display interest list
 194  *
 195  * Parameters
 196  *    hdl        Opaque list handle.
 197  *    b          Output buffer.
 198  * Returns:
 199  *    BCME_OK     Event list successfully dumped.
 200  *    BCME_ERROR  General error.
 201  */
 202 int bcm_notif_dump_list(bcm_notif_h hdl, struct bcmstrbuf *b);
 203
 204 #endif /* BCM_NOTIF_PUB_H */