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 */
  41
  42 #ifndef RM_POLICY_H_
  43 #define RM_POLICY_H_
  44
  45 #ifdef __cplusplus
  46 extern "C" {
  47 #endif
  48
  49 /* RM includes */
  50 #include <ti/drv/rm/rm.h>
  51
  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
  60
  61 /**
  62  * @brief Policy handle (Flattened Device Tree (fdt) blob format)
  63  */
  64 typedef void *Rm_PolicyHandle;
  65
  66 /**
  67  * @brief Result of RM policy operations
  68  */
  69 typedef int32_t   Rm_PolicyResult;
  70
  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;
  80
  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);
  95
  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);
 119
 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.
 122
 123 /* Policy create/delete APIs */
 124
 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);
 129
 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 ...);
 136
 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
 143
 144 /**
 145 @}
 146 */
 147
 148 #ifdef __cplusplus
 149 }
 150 #endif
 151
 152 #endif /* RM_POLICY_H_ */