completed request/response infrastructure
[keystone-rtos/rm-lld.git] / rmservices.h
1 /**
2  *   @file  rmservices.h
3  *
4  *   @brief   
5  *      This is the RM include file for services provided to components that 
6  *      register a RM instance
7  *
8  *  \par
9  *  ============================================================================
10  *  @n   (C) Copyright 2012, Texas Instruments, Inc.
11  * 
12  *  Redistribution and use in source and binary forms, with or without 
13  *  modification, are permitted provided that the following conditions 
14  *  are met:
15  *
16  *    Redistributions of source code must retain the above copyright 
17  *    notice, this list of conditions and the following disclaimer.
18  *
19  *    Redistributions in binary form must reproduce the above copyright
20  *    notice, this list of conditions and the following disclaimer in the 
21  *    documentation and/or other materials provided with the   
22  *    distribution.
23  *
24  *    Neither the name of Texas Instruments Incorporated nor the names of
25  *    its contributors may be used to endorse or promote products derived
26  *    from this software without specific prior written permission.
27  *
28  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
29  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
30  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
31  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
32  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
33  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
34  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
35  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
36  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
37  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
38  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39  *
40  *  \par
41 */
43 #ifndef RMSERVICES_H_
44 #define RMSERVICES_H_
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
50 /**
51 @addtogroup RMSERVICES_API
52 @{
53 */
55 /** RM Service Request (serviceResult) Action Codes and Errors */
56 /** RM Service Request Action Code Base */
57 #define RM_SERVICE_ACTION_BASE (0)
58 /** RM internal action okay - This value is for internal use by RM.  It should never be
59  *  seen as a return value during normal operation */
60 #define RM_SERVICE_ACTION_OKAY (RM_SERVICE_ACTION_BASE)
61 /** RM service was approved.  The resource data in the response is valid if
62  *  the service has been approved. */
63 #define RM_SERVICE_APPROVED (RM_SERVICE_ACTION_BASE+1)
64 /** Beginning of resource denied reasons */
65 #define RM_SERVICE_DENIED_BEGIN (RM_SERVICE_ACTION_BASE+2)
66 /** End of resource denied reasons */
67 #define RM_SERVICE_DENIED_END (RM_SERVICE_ACTION_BASE+2)
68 /** RM service is being processed.  Typically this means the service is
69  *  being sent to a higher level RM agent for processing */
70 #define RM_SERVICE_PROCESSING (RM_SERVICE_ACTION_BASE+3)
72 /** RM Service Request Error Code Base */
73 #define RM_SERVICE_ERROR_BASE (-64)
74 /** RM service request type not recognized */
75 #define RM_SERVICE_ERROR_INVALID_SERVICE_TYPE (RM_SERVICE_ERROR_BASE)
76 /** RM Service request was not provided a component callback
77  *  function.  Service requests may result in blocking operations.  A callback
78  *  function must always be provided with a service request since
79  *  blocked or non-blocked operations cannot be promised.  */
80 #define RM_SERVICE_ERROR_CALLBACK_NOT_PROVIDED (RM_SERVICE_ERROR_BASE-1)
81 /** RM service request needs to be forwarded to another RM agent but no transports
82  *  have been registered */
83 #define RM_SERVICE_ERROR_NO_TRANSPORT_REGISTERED (RM_SERVICE_ERROR_BASE-2)
84 /** RM service request needs to be forwarded but no client delegate or server has 
85  *  been registered with the RM instance */
86 #define RM_SERVICE_ERROR_NOT_REGISTERED_WITH_DEL_OR_SERVER (RM_SERVICE_ERROR_BASE-3)
87 /** RM service request needs to be forwarded but the transport packet alloc API
88  *  has not been provided */
89 #define RM_SERVICE_ERROR_TRANSPORT_PKT_ALLOC_API_NULL (RM_SERVICE_ERROR_BASE-4)
90 /** A failure occurred within a registered transport's packet alloc API */
91 #define RM_SERVICE_ERROR_TRANSPORT_ALLOC_PKT_ERROR (RM_SERVICE_ERROR_BASE-5)
92 /** RM service request needs to be forwarded but the buffer allocated by transport
93  *  is not large enough to fit the RM transport packet */
94 #define RM_SERVICE_ERROR_TRANSPORT_PKT_BUF_TOO_SMALL (RM_SERVICE_ERROR_BASE-6)
95 /** RM service request needs to be forwarded but the transport returned an error
96  *  when trying to send the RM packet to the higher level agent */
97 #define RM_SERVICE_ERROR_TRANPSPORT_SEND_ERROR (RM_SERVICE_ERROR_BASE-7)
98 /** RM service response from higher level agent did not match any requests made
99  *  by the provided RM instance */
100 #define RM_SERVICE_ERROR_TRANSACTION_DOES_NOT_EXST_FOR_THIS_RM_INSTANCE (RM_SERVICE_ERROR_BASE-8)
101 /** RM failed to allocate memory for new service transaction */
102 #define RM_SERVICE_ERROR_TRANSACTION_FAILED_TO_ALLOCATE (RM_SERVICE_ERROR_BASE-9)
103 /** RM found no service transactions queued when trying to delete a received service
104  *  transaction */
105 #define RM_SERVICE_ERROR_NO_TRANSACTIONS_IN_QUEUE (RM_SERVICE_ERROR_BASE-10)
106 /** RM could not find the service transaction in the RM instance's transaction queue */
107 #define RM_SERVICE_ERROR_SERVICE_TRANSACTION_DOES_NOT_EXIST (RM_SERVICE_ERROR_BASE-11)
108 /** RM received a response transaction and found a request transaction awaiting a response.
109  *  However, the request transaction was not in the "awaiting response" state */
110 #define RM_SERVICE_ERROR_INVALID_REQUEST_TRANSACTION_STATE_UPON_RESPONSE (RM_SERVICE_ERROR_BASE-12)
111 /** RM Client instance received a service transaction response that did not have a
112  *  matching service request that originated on the Client instance */
113 #define RM_SERVICE_ERROR_INVALID_TRANSACTION_RECEIVED_ON_CLIENT (RM_SERVICE_ERROR_BASE-13)
114 /** A failure occurred within a registered transport's packet free API */
115 #define RM_SERVICE_ERROR_TRANSPORT_FREE_PKT_ERROR (RM_SERVICE_ERROR_BASE-14)
116 /** Invalid NameServer object create on non-Server instance */
117 #define RM_SERVICE_ERROR_NAMESERVER_OBJECT_CREATE_ON_INVALID_INSTANCE (RM_SERVICE_ERROR_BASE-15)
118 /** Invalid NameServer object delete on non-Server instance */
119 #define RM_SERVICE_ERROR_NAMESERVER_OBJECT_DELETE_ON_INVALID_INSTANCE (RM_SERVICE_ERROR_BASE-16)
121 /** RM Transport Error Code Base */
122 #define RM_TRANSPORT_ERROR_BASE (-128)
123 /** The transport handle provided to the RM instance was not registered with the RM instance */
124 #define RM_TRANSPORT_ERROR_TRANSPORT_HANDLE_NOT_REGISTERED_WITH_INSTANCE (RM_TRANSPORT_ERROR_BASE)
125 /** RM received a packet with an unknown RM packet type */
126 #define RM_TRANSPORT_ERROR_INVALID_PACKET_TYPE (RM_TRANSPORT_ERROR_BASE-1)
128 /** 
129  * @brief RM service types
130  */
131 typedef enum {
132     /** First service type.  Used by RM for bounds checking.  Should
133      *  not be used by component. */
134     Rm_service_FIRST = 0,
135     /** RM resource allocate service */
136     Rm_service_RESOURCE_ALLOCATE = 0,
137     /** RM resource block allocate service */
138     Rm_service_RESOURCE_BLOCK_ALLOCATE = 1,
139     /** RM resource allocate by name service */
140     Rm_service_RESOURCE_ALLOCATE_BY_NAME = 2,    
141     /** RM resource free service */
142     Rm_service_RESOURCE_FREE = 3,
143     /** RM resource block free service */
144     Rm_service_RESOURCE_BLOCK_FREE = 4,
145     /** RM resource free by name service */
146     Rm_service_RESOURCE_FREE_BY_NAME = 5,
147     /** RM resource mapping to name service */
148     Rm_service_RESOURCE_MAP_TO_NAME = 6,
149     /** RM resource name unmapping service */
150     Rm_service_RESOURCE_UNMAP_NAME = 7,
151     /** Last service type.  Used by RM for bounds checking.  Should
152      *  not be used by component. */
153     Rm_service_LAST = 7
154 } Rm_ServiceType;
156 /** 
157  * @brief RM service response information provided by RM back to the 
158  *        requesting component
159  */
160 typedef struct {
161     /** Result of the service request
162      *  Non-negative result: RM has taken an action based on the request
163      *  Negative result: RM has encountered an error handling the request */
164     int32_t serviceResult;
165     /** A request ID will be returned to the component if the requested service cannot
166      *  be completed immediately.  The request ID can be used by the component to identify
167      *  service responses received via the component callback function.  A request ID will not
168      *  be returned if the service request is satisfied immediately */
169     uint32_t requestId;
170     /** The base value of the returned resource.  In the case of a block resource allocation 
171      *  response this field will contain the base value of the block. */
172     int32_t resourceBase;
173     /** The range of resources starting from resourceBase allocated in block requests */
174     uint32_t resourceRange;
175 } Rm_ServiceRespInfo;
177 /** 
178  * @brief RM service request information provided by the requesting component
179  */
180 typedef struct {
181     /** The type of RM service requested */
182     Rm_ServiceType type;
183     /** Pointer to the name of the resource requested.  The 
184      *  name provided by the component must match the resource node names
185      *  provided in the global resource table and allocation policies */
186     char *resourceName;
187 /** An allocate service can be requested with an unspecified resource base. 
188  *  If this occurs the RM Client Delegate or Server will assign the next available
189  *  resource or set of resources based on the allocation type. */
190 #define RM_RESOURCE_BASE_UNSPECIFIED (-1)  
191     /** The resource base value. */
192     int32_t resourceBase;
193     /** The range of the specified resource to be allocated starting from 
194      *  resourceBase.  Will be greater than one only for block allocate
195      *  and free service requests. */
196     uint32_t resourceRange;
197 /** An allocate service can be requested with an unspecified resource alignment.
198  *  WARNING: Only applicapable if resourceBase is unspecified
199  *
200  *  If the alignment is unspecified the RM Client Delegate or Server will allocate
201  *  the resources from a default alignment as specified in the global policy. */
202 #define RM_RESOURCE_ALIGNMENT_UNSPECIFIED (-1)      
203     /** Resource alignment in block allocation requests */
204     int32_t resourceAlignment;
205     /** The name server name associated with the resource.  Used only for 
206      *  allocate and free by name service requests */
207     char *resourceNsName;
208     /** Component callback function.  RM will call this function when the 
209      *  resource service request is completed. The callback function supplied
210      *  for this parameter must match this function pointer prototype. */
211     void (*serviceCallback) (Rm_ServiceRespInfo *serviceResponse);
212 } Rm_ServiceReqInfo;
214 /** 
215  * @brief RM Service Port provided to software components and applications that 
216  *        request RM services for the resources they wish to use
217  */
218 typedef struct {
219     /** RM instance handle for which the service handle was registered */
220     void *rmHandle;
221     /**
222      *  @b Description
223      *  @n  
224      *      Callout function used by components to request a resource service 
225      *      from a RM instance
226      *
227      *   @param[in] rmHandle
228      *      RM instance handle specifying the RM instance that should handle the
229      *      service request
230      *  
231      *  @param[in]  serviceRequest
232      *      Service request structure that provides details of the service requested from
233      *      the RM instance tied to this component
234      *
235      *  @param[in]  serviceResponse
236      *      Service response structure that provides details of RM's response to the
237      *      service request
238      */
239     void (*rmService)(void *rmHandle, Rm_ServiceReqInfo *serviceRequest,
240                       Rm_ServiceRespInfo *serviceResponse);
241 } Rm_ServicesPort;
243 /** 
244 @} 
245 */
247 #ifdef __cplusplus
249 #endif
251 #endif /* RMSERVICES_H_ */