completed request/response infrastructure
[keystone-rtos/rm-lld.git] / include / rmtransportloc.h
1 /*
2  *  file  rmtransportloc.h
3  *
4  *  Private data structures of Resource Manager transport layer.
5  *
6  *  ============================================================================
7  *      (C) Copyright 2012, Texas Instruments, Inc.
8  * 
9  *  Redistribution and use in source and binary forms, with or without 
10  *  modification, are permitted provided that the following conditions 
11  *  are met:
12  *
13  *    Redistributions of source code must retain the above copyright 
14  *    notice, this list of conditions and the following disclaimer.
15  *
16  *    Redistributions in binary form must reproduce the above copyright
17  *    notice, this list of conditions and the following disclaimer in the 
18  *    documentation and/or other materials provided with the   
19  *    distribution.
20  *
21  *    Neither the name of Texas Instruments Incorporated nor the names of
22  *    its contributors may be used to endorse or promote products derived
23  *    from this software without specific prior written permission.
24  *
25  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
26  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
27  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
28  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
29  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
30  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
31  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
34  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
35  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36  *
37  *  \par
38 */
40 #ifndef RMTRANSPORTLOC_H_
41 #define RMTRANSPORTLOC_H_
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
47 /* Device Include */
48 #include <c6x.h>
50 /* RM external includes */
51 #include <ti/drv/rm/rm.h>
53 /* RM internal includes */
54 #include <ti/drv/rm/include/rmloc.h>
56 /** Pointer to RM instance's transport routing map */
57 typedef void *Rm_TransRouteMap;
59 /**
60  * @brief RM transport routing map linked list node.  The created 
61  *        transport nodes are provided to the application casted
62  *        as a Rm_TransportHandle
63  */
64 typedef struct {
65     /** The remote RM instance type */
66     Rm_InstType remoteInstType;
67     /** The remote RM instance name */
68     char remoteInstName[RM_INSTANCE_NAME_MAX_CHARS];
69     /** Link to the next route node in the route map list */
70     Rm_TransportNode *nextNode;
71 } Rm_TransportNode;
73 /**********************************************************************
74  ************************* RM Packet Defs *****************************
75  **********************************************************************/
77 /** 
78  * @brief Resource Request Packet Types
79  */
80 typedef enum {
81     /** Resource allocation request */
82     Rm_resReqPktType_ALLOCATE = 0,
83     /** Block resource allocation request */
84     Rm_resReqPktType_BLOCK_ALLOCATE = 1,
85     /** Resource allocate by name */
86     Rm_resReqPktType_ALLOCATE_NAMED = 2,
87     /** Free resource */
88     Rm_resReqPktType_FREE = 3,
89     /** Free resource block */
90     Rm_resReqPktType_BLOCK_FREE = 4,
91     /** Free named resource */
92     Rm_resReqPktType_FREE_NAMED = 5
93 } Rm_ResourceReqPktType;
95 /** 
96  * @brief Resource Request Packet - Packet sent to higher level RM agents to request
97  *        a resource service that cannot be handled on the local RM instance due to 
98  *        permission restrictions.
99  */
100 typedef struct {
101     /** The transaction ID associated with the request packet */
102     uint32_t requestId;  
103     /** The resource request type */
104     Rm_ResourceReqPktType resourceReqType;
105     /** Name of RM instance that is issuing the resource request. The instance 
106      *  name will be used to validate the request against the RM policy defined
107      *  for the instance. */
108     char instName[RM_INST_NAME_MAX_CHARS];      
109     /** Resource request information */
110     Rm_ResourceInfo resourceInfo;
111 } Rm_ResourceRequestPkt;
113 /** 
114  * @brief Resource Response Packet - Packet sent to RM instances that requested
115  *        a resource service from a higher level RM agent.  The packet will contain
116  *        resource response information based on the request
117  */
118 typedef struct {
119     /** responseID will equal the requestId received in the resource request
120      *  packet.  This ID should be associated with a transaction stored in 
121      *  the RM instance that sent the resource request packet */
122     uint32_t responseId;
123     /** Result of the request.  Resource request, denied, or error.  The
124      *  return values are externally visible so they're tracked in rmservice.h */
125     int32_t requestResult;
126     /* Resource response information */
127     Rm_ResourceInfo resourceInfo;
128 } Rm_ResourceResponsePkt;
130 /** 
131  * @brief NameServer Request Packet Types
132  */
133 typedef enum {
134     /** Request to map the specified name to the specified resources */
135     Rm_nsReqPktType_MAP_RESOURCE = 0,
136     /** Request to unmap the specified name from the specifed resources */
137     Rm_nsReqPktType_UNMAP_RESOURCE = 1
138 } Rm_NsReqPktType;
140 /** 
141  * @brief NameServer Request Packet - Packet sent by RM instances containing
142  *        NameServer mapping or unmapping data
143  */
144 typedef struct {
145     /** The transaction ID associated with the request packet */
146     uint32_t requestId;  
147     /** The resource request type */
148     Rm_NsReqPktType nsRequestType;
149     /** RM instance name making the request.  Policies may restrict who
150      *  can and cannot map and unmap resources via the RM NameServer */
151     char instName[RM_INST_NAME_MAX_CHARS];
152     /** Resource request information */
153     Rm_ResourceInfo resourceInfo;
154 } Rm_NsRequestPkt;
156 /** 
157  * @brief NameServer Response Packet - Provides NameServer transaction response
158  *        data to RM instances that request a name map or unmap
159  */
160 typedef struct {
161     /** responseID will equal the requestId received in the resource request
162      *  packet.  This ID should be associated with a transaction stored in 
163      *  the RM instance that sent the resource request packet */
164     uint32_t responseId;
165     /** Result of the request.  Resource request, denied, or error.  The
166      *  return values are externally visible so they're tracked in rmservice.h */
167     int32_t requestResult;
168 } Rm_NsResponsePkt;
170 /** 
171  * @brief Policy Request Packet - Packet used by a RM instance to request an
172  *        update to its policy data (supported on Client Delegates and Servers only)
173  */
174 typedef struct {
175     /** The transaction ID associated with the request packet */
176     uint32_t requestId;  
177     /** Name of RM instance that is issuing the policy request. The instance 
178      *  name will be used to validate the request against the RM policy defined
179      *  for the instance in the global policy.
180      *  WARNING: Only Client Delegates and Servers can request policy updates */
181     char instName[RM_INST_NAME_MAX_CHARS];      
182 } Rm_PolicyRequestPkt;
184 /** 
185  * @brief Policy Change Packet - Provides policy changes to RM instances that
186  *        support policy storage (Client Delegates and Servers)
187  */
188 typedef struct {
189     /** responseID will equal the requestId received in the resource request
190      *  packet.  This ID should be associated with a transaction stored in 
191      *  the RM instance that sent the resource request packet */
192     uint32_t responseId;
193     /** Byte array containing new policy data for receiving RM instance */
194     char policyData[RM_MAX_POLICY_SIZE_BYTES];
195 } Rm_PolicyChangePkt;
197 /** 
198  * @brief Resource Pool Modification Request Packet Types
199  */
200 typedef enum {
201     /** Resource pool allocation request */
202     Rm_resPoolModType_ALLOCATE = 0,
203     /** Resource pool free request */
204     Rm_resPoolModType_FREE = 1
205 } Rm_ResourcePoolModReqType;
207 /** 
208  * @brief Resource Pool Modification Request Packet - Packet sent to RM Server from
209  *        RM Client Delegates in order to request resource pool modifications on
210  *        the Client Delegate.  The Client Delegate can request more resource's for
211  *        its local resource pool or it can free resources from its resource pool back
212  *        to the Server. */
213 typedef struct {
214     /** The transaction ID associated with the request packet */
215     uint32_t requestId;  
216     /** The resource pool modification request type */
217     Rm_ResourcePoolModReqType resourcePoolModReqType;
218     /** Name of RM Client Delegate instance that is issuing the resource pool 
219      *  modification request. The instance name will be used to validate the 
220      *  request against the RM policy defined for the instance. */
221     char instName[RM_INST_NAME_MAX_CHARS];      
222     /** Resource pool resource request information */
223     Rm_ResourceInfo resourceInfo;
224 } Rm_ResourcePoolModRequestPkt;
226 /** 
227  * @brief Resource Pool Modification Response Packet - Packet sent to RM Client
228  *        Delegates from RM Servers in response to resource pool modification requests.
229  *        The packet will contain resource response information based on the request
230  */
231 typedef struct {
232     /** responseID will equal the requestId received in the resource pool mod request
233      *  packet.  This ID should be associated with a transaction stored in 
234      *  the RM instance that sent the resource request packet */
235     uint32_t responseId;
236     /** Result of the resource pool mod request.  Resource request, denied, or error.  The
237      *  return values are externally visible so they're tracked in rmservice.h */
238     int32_t requestResult;
239     /* Resource pool resource response information */
240     Rm_ResourceInfo resourceInfo;
241 } Rm_ResourcePoolModResponsePkt;
243 #ifdef __cplusplus
245 #endif
247 #endif /* RMTRANSPORTLOC_H_ */