1 /**
2 * @file rm_services.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-2013, 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 /* RM includes */
51 #include <ti/drv/rm/rm.h>
53 /**
54 @addtogroup RM_SERVICES_API
55 @{
56 */
58 /**
59 * @brief RM service types
60 */
61 typedef enum {
62 /** RM resource allocate for initialization service */
63 Rm_service_RESOURCE_ALLOCATE_INIT = 0,
64 /** RM resource allocate for use service */
65 Rm_service_RESOURCE_ALLOCATE_USE,
66 /** RM resource free service */
67 Rm_service_RESOURCE_FREE,
68 /** RM resource status service - returns the reference count for specified
69 * resource. */
70 Rm_service_RESOURCE_STATUS,
71 /** RM NameServer map resource to name service */
72 Rm_service_RESOURCE_MAP_TO_NAME,
73 /** RM NameServer get resource by name service */
74 Rm_service_RESOURCE_GET_BY_NAME,
75 /** RM NameServer unmap resource from name service */
76 Rm_service_RESOURCE_UNMAP_NAME,
77 /** DO NOT USE: Last type */
78 Rm_service_LAST
79 } Rm_ServiceType;
81 /**
82 * @brief RM service response information used by RM to provide service
83 * request results back to the application components
84 */
85 typedef struct {
86 /** RM instance handle from which the service request that spawned this
87 * result originated. Used by application to sort responses, received
88 * via callback function, from RM instances located on the same core. */
89 Rm_Handle rmHandle;
90 /** Service request state. State values can be found in rm.h starting
91 * with #RM_SERVICE_PROCESSING, #RM_SERVICE_DENIED_BASE, and
92 * #RM_ERROR_LIBFDT_START */
93 int32_t serviceState;
94 /** The service ID is returned to the application in order to match service
95 * responses received at a later time via the provided callback function
96 * because RM required a blocking operation in order to satisfy the
97 * resource request. <br> <br> The service ID will never have a value of
98 * zero. */
99 uint32_t serviceId;
100 /** Affected resource name */
101 char resourceName[RM_NAME_MAX_CHARS];
102 /** The resource base value allocated, freed, or mapped to NameServer name. */
103 int32_t resourceBase;
104 /** The resource length starting at base allocated, freed, or mapped to
105 * NameServer name. */
106 uint32_t resourceLength;
107 /** resourceNumOwners is not valid unless >= 0 */
108 #define RM_RESOURCE_NUM_OWNERS_INVALID (-1)
109 /** Current number of owners for the returned resource. A value greater
110 * than one means the resource is being shared. This value is only valid
111 * if the serviceState is RM_SERVICE_APPROVED or RM_SERVICE_APPROVED_STATIC. */
112 int32_t resourceNumOwners;
113 } Rm_ServiceRespInfo;
115 /**
116 * @brief RM service callback function
117 */
118 typedef struct {
119 /** Component callback function. RM calls this function when a blocking
120 * resource service request is complete. The callback function supplied
121 * for this parameter must match the function pointer prototype. */
122 void (*serviceCallback) (Rm_ServiceRespInfo *serviceResponse);
123 } Rm_ServiceCallback;
125 /**
126 * @brief RM service request information
127 */
128 typedef struct {
129 /** The type of service requested */
130 Rm_ServiceType type;
131 /** Pointer to an array containing the resource name affected by
132 * the request. The resource name must match a resource node name
133 * defined in the GRL and global/static policy. The request will be
134 * denied if the resource name does not match any resource node names
135 * in the policy */
136 const char *resourceName;
137 /** Informs RM to find the next available resource block of length
138 * resourceLength and alignment resourceAlignment for allocation. This
139 * parameter is only valid for resource allocate service types. */
140 #define RM_RESOURCE_BASE_UNSPECIFIED (-1)
141 /** The base value of the resource affected by the service request.
142 * #RM_RESOURCE_BASE_UNSPECIFIED can be substituted. */
143 int32_t resourceBase;
144 /** The resource length, starting from #resourceBase affected by the
145 * service request. */
146 uint32_t resourceLength;
147 /** Informs RM to find the next available resource block with length
148 * resourceLength and the alignment specified in
149 * a) The resource node in the policy if it has the "allocation-alignment"
150 * property defined.
151 * b) The default alignment of 1 if no alignment is specified in the policy
152 * for the resource.
153 * This value is only valid if resourceBase is set to #RM_RESOURCE_BASE_UNSPECIFIED */
154 #define RM_RESOURCE_ALIGNMENT_UNSPECIFIED (-1)
155 /** Alignment of the resource affected by the service request. Only valid
156 * if resourceBase is set to #RM_RESOURCE_BASE_UNSPECIFIED.
157 * #RM_RESOURCE_ALIGNMENT_UNSPECIFIED can be substituted. */
158 int32_t resourceAlignment;
159 /** The NameServer name associated, or to be associated, with a resource.
160 * The NameServer name has precedence over #resourceBase and #resourceLength
161 * for all resource modification service types as well as
162 * #Rm_service_RESOURCE_GET_BY_NAME. If the NameServer name and the base
163 * and length are not NULL the resource information retrieved from the
164 * NameServer entry for the name will replace the values present in
165 * #resourceBase and #resourceLength */
166 const char *resourceNsName;
167 /** Callback function used by RM to provide responses back to application
168 * components after a service request resulted in a blocking operation.
169 * If no callback function is provided the RM instance will block until
170 * the service response is ready. */
171 Rm_ServiceCallback callback;
172 } Rm_ServiceReqInfo;
174 /**
175 * @brief RM service handle provided to application components for requesting
176 * services
177 */
178 typedef struct {
179 /** RM instance handle from which the service handle was allocated from. */
180 void *rmHandle;
181 /**
182 * @b Description
183 * @n
184 * Processes service requests from application components. Responses
185 * are returned immediately if the service request could be satisfied
186 * without blocking. If the service request requires a blocking operation,
187 * such as forwarding the service request to another instance for
188 * validation, the response will be received via the Rm_ServerCallback
189 *
190 * @param[in] rmHandle
191 * RM instance handle specifies the instance that handles the service
192 * request. The request's result, if policy checks are involved, will be
193 * based on the permissions assigned to the rmHandle's instance name within
194 * global/static policy.
195 *
196 * @param[in] serviceRequest
197 * Pointer to the service request structure
198 *
199 * @param[out] serviceResponse
200 * Pointer to a service response structure.
201 */
202 void (*Rm_serviceHandler)(void *rmHandle, const Rm_ServiceReqInfo *serviceRequest,
203 Rm_ServiceRespInfo *serviceResponse);
204 } Rm_ServiceHandle;
206 /**
207 * @b Description
208 * @n
209 * This function returns a RM service handle to the application to
210 * provide services to software components (LLDs, BIOS, etc) that want to use RM
211 * for resource management. Only one service handle can be opened from
212 * each RM instance.
213 *
214 * @param[in] rmHandle
215 * RM instance handle from which the service handle will be opened
216 *
217 * @param[out] result
218 * Pointer to a signed int used to return any errors encountered during
219 * the instance initialization process.
220 *
221 * @retval
222 * Success - Rm_ServiceHandle and result = #RM_OK
223 * @retval
224 * Failure - NULL Rm_ServiceHandle and result = #RM_ERROR_SERVICE_HANDLE_MEM_ALLOC_FAILED
225 */
226 Rm_ServiceHandle *Rm_serviceOpenHandle(Rm_Handle rmHandle, int32_t *result);
228 /**
229 * @b Description
230 * @n
231 * This function closes a RM instance's service handle
232 *
233 * @param[in] rmServiceHandle
234 * RM instance service handle to be closed.
235 *
236 * @retval
237 * Success - #RM_OK
238 * @retval
239 * Failure - #RM_ERROR_SERVICE_HANDLE_ALREADY_CLOSED
240 */
241 int32_t Rm_serviceCloseHandle(Rm_ServiceHandle *rmServiceHandle);
243 /**
244 @}
245 */
247 #ifdef __cplusplus
248 }
249 #endif
251 #endif /* RM_SERVICES_H_ */