Tested ability to read in and parse resource and policy DTB files
[keystone-rtos/rm-lld.git] / rm_policy.h
1 /**
2  *   @file  rm_policy.h
3  *
4  *   @brief   
5  *      This is the RM include file for the policy APIs
6  *
7  *  \par
8  *  ============================================================================
9  *  @n   (C) Copyright 2012, Texas Instruments, Inc.
10  * 
11  *  Redistribution and use in source and binary forms, with or without 
12  *  modification, are permitted provided that the following conditions 
13  *  are met:
14  *
15  *    Redistributions of source code must retain the above copyright 
16  *    notice, this list of conditions and the following disclaimer.
17  *
18  *    Redistributions in binary form must reproduce the above copyright
19  *    notice, this list of conditions and the following disclaimer in the 
20  *    documentation and/or other materials provided with the   
21  *    distribution.
22  *
23  *    Neither the name of Texas Instruments Incorporated nor the names of
24  *    its contributors may be used to endorse or promote products derived
25  *    from this software without specific prior written permission.
26  *
27  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
28  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
29  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
30  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
31  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
32  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
33  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
34  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
35  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
36  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
37  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38  *
39  *  \par
40 */
42 #ifndef RM_POLICY_H_
43 #define RM_POLICY_H_
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
49 /* RM includes */
50 #include <ti/drv/rm/rm.h>
52 /**
53 @addtogroup RM_POLICY_API
54 @{
55 */
56 /**
57  * @brief Maximum number of characters in the policy name
58  */
59 #define RM_MAX_POLICY_NAME_LENGTH 8
61 /**
62  * @brief Policy handle (Flattened Device Tree (fdt) blob format)
63  */
64 typedef void *Rm_PolicyHandle;
66 /** 
67  * @brief Result of RM policy operations
68  */
69 typedef int32_t   Rm_PolicyResult;
71 /**
72  * @brief Structure populated by policy API with basic RM policy information
73  */
74 typedef struct {
75     /** Policy name */
76     char policyName[RM_MAX_POLICY_NAME_LENGTH] ;
77     /** Policy handle */
78     Rm_PolicyHandle policyHandle;
79 } Rm_PolicyInfo;
81 /**
82  *  @b Description
83  *  @n  
84  *      This function returns the number of policies located within a RM
85  *      instance tree
86  *
87  *  @param[in]  serverHandle
88  *      RM tree's server handle.  Used to report the number of policies for
89  *      the given server handle's instance tree
90  *
91  *  @retval
92  *      Number of policies located within the instance tree
93  */
94 uint32_t Rm_numPoliciesInTree(Rm_Handle serverHandle);
96 /**
97  *  @b Description
98  *  @n  
99  *      This function returns a list of all policies within the system.  The
100  *      list will contain a policy name and handle for each policy.
101  *
102  *  @param[in]  serverHandle
103  *      RM tree's server handle.  Used to query the policy information for
104  *      the given server handle's instance tree
105  *
106  *  @param[in]  *policyInfoArray
107  *      An array of Rm_PolicyInfo structures that will contain information for
108  *      all policies within the instance tree upon function return.
109  *
110  *      Note: The size of the array passed must be equal to or greater than 
111  *            the number of policies returned by the Rm_numPoliciesInTree API
112  *
113  *  @retval
114  *      SUCCESS - 0
115  *  @retval
116  *      FAILURE - non-zero value
117  */
118 Rm_PolicyResult Rm_listPolicies(Rm_Handle serverHandle, Rm_PolicyInfo *policyInfoArray);
120 #if 0
121 The following API input parameters are not finalized yet as they are a wrapper around the DTB modification APIs provided in the dtc library.  The input parameters will be finalized as the operation of the dtc API is better understood.
123 /* Policy create/delete APIs */
125 /* May not allow additional input parameters.  Created policies can be
126  * modified using the policy modification APIs */
127 Rm_PolicyHandle Rm_createPolicy(Rm_Handle serverHandle, ...);
128 Rm_PolicyResult Rm_deletePolicy(Rm_PolicyHandle);
130 /* Policy modification APIs */
131 Rm_PolicyResult Rm_addInstToPolicy(Rm_PolicyHandle, ...);
132 Rm_PolicyResult Rm_deleteInstFromPolicy(Rm_PolicyHandle, ...);
133 Rm_PolicyResult Rm_addResourceToPolicy(Rm_PolicyHandle, instName, ...);
134 Rm_PolicyResult Rm_deleteResourceFromPolicy(Rm_PolicyHandle, instName, ...);
135 Rm_PolicyResult Rm_modifyResourceProp(Rm_PolicyHandle, instName, resName ...);
137 /* Read Policy APIs */
138 Rm_PolicyResult Rm_listPolicyInstances(Rm_PolicyHandle, ...);
139 Rm_PolicyResult Rm_listInstResources(Rm_PolicyHandle, instName, ...);
140 Rm_PolicyResult Rm_listPolicyResourceProperties(Rm_PolicyHandle, instName, 
141                                                 resourceName, ...);
142 #endif
144 /** 
145 @} 
146 */
148 #ifdef __cplusplus
150 #endif
152 #endif /* RM_POLICY_H_ */