Checking in RMv2 progress
[keystone-rtos/rm-lld.git] / rm_services.h
1 /**
2  *   @file  rm_services.h
3  *
4  *   @brief   
5  *      This is the RM include file for services provided to components that register a RM 
6  *      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 RM_SERVICES_H_
44 #define RM_SERVICES_H_
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
50 /**
51 @addtogroup RM_SERVICES_API
52 @{
53 */
55 /** 
56  * @brief RM will return the next available resource if the component assigns 
57  *        "not specified" in the resourceIndex field when the resource allocate
58  *        service is initiated.        
59  */
60 #define RM_SERVICE_INDEX_NOT_SPECIFIED (-1)
62 /** 
63  * @brief Result of requested RM service
64  */
65 typedef enum {
66     /** RM Service was okay */
67     RM_service_OKAY = 0,
68     /** RM Service request not recognized */
69     RM_service_INVALID_SERVICE_TYPE = 1
70 } Rm_ServiceResult;
72 /** 
73  * @brief RM service types
74  */
75 typedef enum {
76     /** RM resource allocate service */
77     Rm_service_RESOURCE_ALLOCATE = 0,
78     /** RM resource block allocate service */
79     Rm_service_RESOURCE_BLOCK_ALLOCATE,
80     /** RM resource allocate by name service */
81     Rm_service_RESOURCE_ALLOCATE_BY_NAME,    
82     /** RM resource free service */
83     Rm_service_RESOURCE_FREE,
84     /** RM resource block free service */
85     Rm_service_RESOURCE_BLOCK_FREE,
86     /** RM resource free by name service */
87     Rm_service_RESOURCE_FREE_BY_NAME,
88     /** RM resource mapping to name service */
89     Rm_service_RESOURCE_MAP_TO_NAME,
90     /** RM resource name unmapping service */
91     Rm_service_RESOURCE_UNMAP_NAME,
92     /** RM resource status service */
93     Rm_service_RESOURCE_STATUS
94 } Rm_ServiceType;
96 /** 
97  * @brief RM service response information provided by RM back to the requesting component
98  */
99 typedef struct {
100     /** A request ID will be returned to the component if the requested service cannot
101      * be completed immediately.  The request ID can be used by the component to identify
102      * service responses received via the component callback function.  A request ID will not
103      * be returned if the service request is satisfied immediately */
104     uint32_t requestId;
105     /** The value of the returned resource.  In the case of a block resource allocation response
106      * this field will contain the base value of the block. */
107     int32_t resBase;
108     /** The number of resources allocated in block requests */
109     uint32_t resNum;
110 } Rm_ServiceRespInfo;
112 /** 
113  * @brief RM service request information provided by the requesting component
114  */
115 typedef struct {
116     /** The type of RM service requested */
117     Rm_ServiceType serviceType;
118     /** Pointer to the name of the resource requested.  The 
119      *  name provided by the component must match the resource node names
120      *  provided in the global resource table and allocation policies */
121     char *resName;
122     /** The resource base value. */
123     int32_t resBase;
124     /** The number of the specified resources.  Will be greater than one only
125      * for block allocate and free service requests. */
126     uint32_t resNum;
127     /** Resource alignment in block allocation requests */
128     uint32_t resAlign;    
129     /** The name server name associated with the resource.  Used only for 
130      * allocate and free by name service requests */
131     char *resNsName;
132     /** Component callback function.  RM will call this function when the 
133      *  resource service request is completed. The callback function supplied
134      *  for this parameter must match this function pointer prototype. */
135     void (*serviceCallback) (Rm_ServiceResult rmResult, char *resourceName,
136                              uint32_t resourceIndex);
137 } Rm_ServiceReqInfo;
140 /** 
141  * @brief RM Service Handle provided to software components that 
142  *        request RM services for the resources they control
143  */
144 typedef struct {
145     /** RM instance handle for which the service handle was registered */
146     void *rmHandle;
147     /**
148      *  @b Description
149      *  @n  
150      *      Callout function used by components to request a resource service 
151      *      from a RM instance
152      *
153      *   @param[in] rmHandle
154      *      RM instance handle specifying the RM instance that should handle the
155      *      service request
156      *  
157      *  @param[in]  requestInfo
158      *      Service request structure that provides details of the service requested from
159      *      the RM instance tied to this component
160      *
161      *  @param[in]  responseInfo
162      *      Service response structure that provides details of RM's response to the
163      *      service request
164      *
165      *  @retval
166      *      Success - 0 - Service request was handled okay.
167      *  @retval
168      *      Failure - non-zero - Service request error.
169      */
170     Rm_ServiceResult  (*rmService)(void *rmHandle, Rm_ServiceReqInfo *requestInfo,
171                                                       Rm_ServiceRespInfo *responseInfo);
172 } Rm_ServicesPort;
174 /** 
175 @} 
176 */
178 #ifdef __cplusplus
180 #endif
182 #endif /* RM_SERVICES_H_ */