SrvMgr: Pulled in ServiceMgr (and OmxSrvMgr) from omapzoom sysbios-rpmsg.
[ipc/ipcdev.git] / 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  */
39 #ifndef ti_srvmgr_ServiceMgr__include
40 #define ti_srvmgr_ServiceMgr__include
42 #include <xdc/std.h>
44 #include <ti/sysbios/knl/Task.h>
45 #include <ti/grcm/RcmServer.h>
48 #if defined (__cplusplus)
49 extern "C" {
50 #endif
53 /* Max number of known service types: */
54 #define ServiceMgr_NUMSERVICETYPES         16
56 /*!
57  *  @brief Service instance object handle
58  */
59 typedef RcmServer_Handle  Service_Handle;
61 /*!
62  *  @brief Service disconnect notifier hook function type definition
63  */
64 typedef Void (*ServiceMgr_disconnectFuncPtr)(Service_Handle srvc, Ptr data);
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();
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);
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);
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);
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);
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);
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);
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);
202 #if defined (__cplusplus)
204 #endif /* defined (__cplusplus) */
206 #endif /* ti_srvmgr_ServiceMgr__include */