/**
 *   @file  rm_policy.h
 *
 *   @brief   
 *      This is the RM include file for the policy APIs
 *
 *  \par
 *  ============================================================================
 *  @n   (C) Copyright 2012, Texas Instruments, Inc.
 * 
 *  Redistribution and use in source and binary forms, with or without 
 *  modification, are permitted provided that the following conditions 
 *  are met:
 *
 *    Redistributions of source code must retain the above copyright 
 *    notice, this list of conditions and the following disclaimer.
 *
 *    Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the 
 *    documentation and/or other materials provided with the   
 *    distribution.
 *
 *    Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
 *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
 *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
 *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
 *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
 *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *  \par
*/

#ifndef RM_POLICY_H_
#define RM_POLICY_H_

#ifdef __cplusplus
extern "C" {
#endif

/* RM includes */
#include <ti/drv/rm/rm.h>

/**
@addtogroup RM_POLICY_API
@{
*/
/**
 * @brief Maximum number of characters in the policy name
 */
#define RM_MAX_POLICY_NAME_LENGTH 8

/**
 * @brief Policy handle (Flattened Device Tree (fdt) blob format)
 */
typedef void *Rm_PolicyHandle;

/** 
 * @brief Result of RM policy operations
 */
typedef int32_t   Rm_PolicyResult;

/**
 * @brief Structure populated by policy API with basic RM policy information
 */
typedef struct {
    /** Policy name */
    char policyName[RM_MAX_POLICY_NAME_LENGTH] ;
    /** Policy handle */
    Rm_PolicyHandle policyHandle;
} Rm_PolicyInfo;

/**
 *  @b Description
 *  @n  
 *      This function returns the number of policies located within a RM
 *      instance tree
 *
 *  @param[in]  serverHandle
 *      RM tree's server handle.  Used to report the number of policies for
 *      the given server handle's instance tree
 *
 *  @retval
 *      Number of policies located within the instance tree
 */
uint32_t Rm_numPoliciesInTree(Rm_Handle serverHandle);

/**
 *  @b Description
 *  @n  
 *      This function returns a list of all policies within the system.  The
 *      list will contain a policy name and handle for each policy.
 *
 *  @param[in]  serverHandle
 *      RM tree's server handle.  Used to query the policy information for
 *      the given server handle's instance tree
 *
 *  @param[in]  *policyInfoArray
 *      An array of Rm_PolicyInfo structures that will contain information for
 *      all policies within the instance tree upon function return.
 *
 *      Note: The size of the array passed must be equal to or greater than 
 *            the number of policies returned by the Rm_numPoliciesInTree API
 *
 *  @retval
 *      SUCCESS - 0
 *  @retval
 *      FAILURE - non-zero value
 */
Rm_PolicyResult Rm_listPolicies(Rm_Handle serverHandle, Rm_PolicyInfo *policyInfoArray);

#if 0
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.

/* Policy create/delete APIs */

/* May not allow additional input parameters.  Created policies can be
 * modified using the policy modification APIs */
Rm_PolicyHandle Rm_createPolicy(Rm_Handle serverHandle, ...);
Rm_PolicyResult Rm_deletePolicy(Rm_PolicyHandle);

/* Policy modification APIs */
Rm_PolicyResult Rm_addInstToPolicy(Rm_PolicyHandle, ...);
Rm_PolicyResult Rm_deleteInstFromPolicy(Rm_PolicyHandle, ...);
Rm_PolicyResult Rm_addResourceToPolicy(Rm_PolicyHandle, instName, ...);
Rm_PolicyResult Rm_deleteResourceFromPolicy(Rm_PolicyHandle, instName, ...);
Rm_PolicyResult Rm_modifyResourceProp(Rm_PolicyHandle, instName, resName ...);

/* Read Policy APIs */
Rm_PolicyResult Rm_listPolicyInstances(Rm_PolicyHandle, ...);
Rm_PolicyResult Rm_listInstResources(Rm_PolicyHandle, instName, ...);
Rm_PolicyResult Rm_listPolicyResourceProperties(Rm_PolicyHandle, instName, 
                                                resourceName, ...);
#endif

/** 
@} 
*/

#ifdef __cplusplus
}
#endif

#endif /* RM_POLICY_H_ */