packages/ti/srvmgr/ServiceMgr.h

   1 /*
   2  * Copyright (c) 2011-2013, Texas Instruments Incorporated
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * *  Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  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  *
  16  * *  Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32 /*
  33  *  ======== service_mgr.c ========
  34  *  Simple server that handles requests to create threads (services) by name
  35  *  and provide an endpoint to the new thread.
  36  *
  37  */
  38
  39 #ifndef ti_srvmgr_ServiceMgr__include
  40 #define ti_srvmgr_ServiceMgr__include
  41
  42 #include <xdc/std.h>
  43
  44 #include <ti/sysbios/knl/Task.h>
  45 #include <ti/grcm/RcmServer.h>
  46
  47
  48 #if defined (__cplusplus)
  49 extern "C" {
  50 #endif
  51
  52
  53 /* Max number of known service types: */
  54 #define ServiceMgr_NUMSERVICETYPES         16
  55
  56 /*!
  57  *  @brief Service instance object handle
  58  */
  59 typedef RcmServer_Handle  Service_Handle;
  60
  61 /*!
  62  *  @brief Service disconnect notifier hook function type definition
  63  */
  64 typedef Void (*ServiceMgr_disconnectFuncPtr)(Service_Handle srvc, Ptr data);
  65
  66 /*
  67  *  ======== ServiceMgr_init ========
  68  */
  69 /*!
  70  *  @brief Initialize the ServiceMgr.
  71  *
  72  *  Currently, this simply initializes the RcmServer module.a
  73  *
  74  */
  75 Void ServiceMgr_init();
  76
  77 /*
  78  *  ======== ServiceMgr_registerSrvTask ========
  79  */
  80 /*!
  81  *  @brief Register a task associated with a service
  82  *
  83  *  This function registers a service task function with the ServiceMgr module.
  84  *  This allows the service tasks to be outside the scope of the ServiceMgr
  85  *  module, and allow users to define their own services with its associated
  86  *  task function. After all the registrations are done, a ServiceMgr_start
  87  *  would start these tasks.
  88  *
  89  *  @param[in] reserved    Reserved for future scalability
  90  *  @param[in] func        Task function to run for a particular service task
  91  *  @param[in] taskParams  Initialized task parameters that will be used to
  92  *                         create the task
  93  *
  94  *  @sa ServiceMgr_start
  95  */
  96 Bool ServiceMgr_registerSrvTask(UInt16 reserved, Task_FuncPtr func,
  97                                 Task_Params *taskParams);
  98
  99 /*
 100  *  ======== ServiceMgr_start ========
 101  */
 102 /*!
 103  *  @brief Start the ServiceMgr services
 104  *
 105  *  This function creates all the task functions associated with the individual
 106  *  services. Each of the tasks is responsible for publishing a service to the
 107  *  remote processor and service all the incoming connection requests on that
 108  *  service.
 109  *
 110  *  @param[in] reserved    Reserved for future scalability
 111  *
 112  *  @sa ServiceMgr_registerTask
 113  */
 114 UInt ServiceMgr_start(UInt16 reserved);
 115
 116 /*
 117  *  ======== ServiceMgr_register ========
 118  */
 119 /*!
 120  *  @brief Register a service with its static function table.
 121  *
 122  *  This function stores the RcmServerParams structure with the name key, which
 123  *  the ServiceMgr will find on a subsequent connect call to instantiate an
 124  *  RcmServer of this name.
 125  *
 126  *  @param[in] name    The name of the server that messages will be sent to for
 127  *  executing commands. The name must be a system-wide unique name.
 128  *
 129  *  @param[in] rcmServerParams  The RcmServer_create params used to initialize
 130  *                              the service instance.
 131  *
 132  *  @sa RcmServer_create
 133  */
 134 Bool ServiceMgr_register(String name, RcmServer_Params  *rcmServerParams);
 135
 136 /*
 137  *  ======== ServiceMgr_send ========
 138  */
 139 /*!
 140  *  @brief Send an asynchrounous message to a service's client endpoint.
 141  *
 142  *  This function uses the reply endpoint registered with the given service
 143  *  by the ServiceMgr, to send a message to the client.  It is meant to
 144  *  be used for asynchronous callbacks from service functions, where the
 145  *  callbacks do not expect a reply (hence, no ServiceMgr_recv is defined).
 146  *
 147  *  @param[in]  srvc    Handle to a service, passed into every service function.
 148  *  @param[in]  data    Data payload to be copied and sent. First structure
 149  *                      must be an omx_hdr
 150  *  @param[in]  len     Amount of data to be copied.
 151  *
 152  */
 153 Void ServiceMgr_send(Service_Handle srvc, Ptr data, UInt16 len);
 154
 155 /*
 156  *  ======== ServiceMgr_registerdisconnectFxn =======
 157  */
 158 /*!
 159  *  @brief Registers a application-specific service disconnect callback function
 160  *
 161  *  @param[in]  srvc           Handle to a service, passed into every service
 162  *                             function
 163  *  @param[in]  data           Pointer to application-specific data passed back
 164  *                             to the disconnect hook function
 165  *  @param[in]  func           Hook function to be called on a service disconnect
 166  *
 167  */
 168 Bool ServiceMgr_registerDisconnectFxn(Service_Handle srvc, Ptr data,
 169                                       ServiceMgr_disconnectFuncPtr func);
 170
 171 /*
 172  *  ======== ServiceMgr_createService =======
 173  */
 174 /*!
 175  *  @brief Create a RCM Server instance associated with a service
 176  *
 177  *  Create a RCM server instance using the set of functions associated with the
 178  *  name, and returns an end point address registered for the service.
 179  *
 180  *  @param[in]  name           Name associated with RCM function set
 181  *  @param[in]  endPt          Endpoint pointer address
 182  *
 183  */
 184 UInt32 ServiceMgr_createService(Char * name, UInt32 * endPt);
 185
 186 /*
 187  *  ======== ServiceMgr_deleteService =======
 188  */
 189 /*!
 190  *  @brief Delete the RCM Server instance associated with an endpoint address
 191  *
 192  *  Deletes the RCM Servver instance associated with a particular endpoint
 193  *  address.
 194  *
 195  *  @param[in]  addr          EndPoint pointer address associated with the
 196  *                            service to delete.
 197  *
 198  */
 199 UInt32 ServiceMgr_deleteService(UInt32 addr);
 200
 201
 202 #if defined (__cplusplus)
 203 }
 204 #endif /* defined (__cplusplus) */
 205
 206 #endif /* ti_srvmgr_ServiceMgr__include */