[keystone-rtos/rm-lld.git] / rm_services.h

/**
 *   @file  rmservices.h
 *
 *   @brief   
 *      This is the RM include file for services provided to components that 
 *      register a RM instance
 *
 *  \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 RMSERVICES_H_
#define RMSERVICES_H_

#ifdef __cplusplus
extern "C" {
#endif

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

/**
@addtogroup RMSERVICES_API
@{
*/

/** RM Service Request State Codes and Errors */
/** RM Service Request State Code Base */
#define RM_SERVICE_STATE_BASE (0)
/** RM internal state okay - This value is for internal use by RM.  It should never be
 *  seen as a return value during normal operation */
#define RM_SERVICE_STATE_OKAY (RM_SERVICE_STATE_BASE)
/** RM service is being processed.  Typically this means the service is
 *  being sent to a higher level RM agent for processing */
#define RM_SERVICE_PROCESSING (RM_SERVICE_STATE_BASE+1)
/** RM service was approved.  The resource data in the response is valid if
 *  the service has been approved. */
#define RM_SERVICE_APPROVED_AND_COMPLETED (RM_SERVICE_STATE_BASE+2)
/** Beginning of resource denied reasons */
#define RM_SERVICE_DENIED_BEGIN (RM_SERVICE_STATE_BASE+3)
/** RM could not find an allocator for the resource specified with the provided name */
#define RM_SERVICE_DENIED_RESOURCE_DOES_NOT_EXIST (RM_SERVICE_DENIED_BEGIN)
/** A resource value within the specifed base+range could not be found within the resource's
 *  allocator.  No action was taken on the resources. */
#define RM_SERVICE_DENIED_RESOURCE_VALUE_RANGE_DOES_NOT_EXIST (RM_SERVICE_DENIED_BEGIN+1)
/** A resource value within the specifed base+range was not allocated to the RM instance
 *  that is the source of the request.  No action was taken on the resources. */
#define RM_SERVICE_DENIED_RESOURCE_NOT_ALLOCATED_TO_INSTANCE_REQUESTING_THE_SERVICE (RM_SERVICE_DENIED_BEGIN+2)
/** A resource value within the specifed base+range is already free */
#define RM_SERVICE_DENIED_RESOURCE_ALREADY_FREE (RM_SERVICE_DENIED_BEGIN+3)
/** A resource value within the specifed base+range is already allocated to another
 *  RM instance. */
#define RM_SERVICE_DENIED_RESOURCE_ALREADY_ALLOCATED (RM_SERVICE_DENIED_BEGIN+4)
/** The resource range specified for freeing included free and allocated resoruces. */
#define RM_SERVICE_DENIED_INVALID_RESOURCE_RANGE (RM_SERVICE_DENIED_BEGIN+5)
/** No free resource ranges could be found that satisfy the resource base, length, and
 *  alignment requirements */
#define RM_SERVICE_DENIED_RESOURCE_ALLOCATION_REQUIREMENTS_COULD_NOT_BE_SATISFIED (RM_SERVICE_DENIED_BEGIN+6)
/** The RM instance requesting the service is not defined in the policy */
#define RM_SERVICE_DENIED_RM_INST_NOT_DEFINED_IN_POLICY (RM_SERVICE_DENIED_BEGIN+7)
/** The resource in the service request is not defined in the policy */
#define RM_SERVICE_DENIED_RESOURCE_NOT_DEFINED_IN_POLICY (RM_SERVICE_DENIED_BEGIN+8)
/** The resource has multiple assigned range definitions */
#define RM_SERVICE_DENIED_ASSIGNED_RANGE_SPECIFICATION_ERROR (RM_SERVICE_DENIED_BEGIN+9)
/** The resource has multiple allocation size definitions */
#define RM_SERVICE_DENIED_ALLOCATION_SIZE_SPECIFICATION_ERROR (RM_SERVICE_DENIED_BEGIN+10)
/** The resource has multiple assigned name definitions */
#define RM_SERVICE_DENIED_ASSIGNED_NAME_SPECIFICATION_ERROR (RM_SERVICE_DENIED_BEGIN+11)
/** The resource has multiple allocation alignment definitions */
#define RM_SERVICE_DENIED_ALLOCATION_ALIGNMENT_SPECIFICATION_ERROR (RM_SERVICE_DENIED_BEGIN+12)
/** The resource node in the policy has an unknown property type */
#define RM_SERVICE_DENIED_UNKNOWN_POLICY_PROPERTY (RM_SERVICE_DENIED_BEGIN+13)
/** The policy does not approve of the resources requested by the RM instance in the service
 *  request */
#define RM_SERVICE_DENIED_POLICY_DENIAL (RM_SERVICE_DENIED_BEGIN+14)
/** Attempt to add object to NameServer denied: The object name already exists in the NameServer */
#define RM_SERVICE_DENIED_NAMESERVER_ERROR_NAME_ALREADY_EXISTS (RM_SERVICE_DENIED_BEGIN+15)
/** No valid ranges were specified for the resource within the RM instance's node within the policy.
 *  By default all resource requests for this resource are denied */
#define RM_SERVICE_DENIED_POLICY_DENIAL_NO_RANGES_SPECIFIED (RM_SERVICE_DENIED_BEGIN+16)
/** The instance name of the service requesting instance is not in the policy valid instance list */
#define RM_SERVICE_DENIED_ORIGINATING_INSTANCE_NAME_NOT_VALID (RM_SERVICE_DENIED_BEGIN+17)
/** The policy does not specify any assignment ranges for the resource in the service request */
#define RM_SERVICE_DENIED_NO_RANGE_ASSIGNMENTS_FOR_POLICY (RM_SERVICE_DENIED_BEGIN+18)
/** The resource couldn't be allocated because the requesting instance was not given the init/use
 *  permissions in the policy */
#define RM_SERVICE_DENIED_INIT_USE_PERMISSION_DENIED (RM_SERVICE_DENIED_BEGIN+19)
/** The resource couldn't be allocated because the requesting instance has exclusive privileges in the
 *  policy but the resource was already allocated */
#define RM_SERVICE_DENIED_REQUESTER_HAS_EXCLUSIVE_PRIV_BUT_RESOURCE_ALLOCATED (RM_SERVICE_DENIED_BEGIN+20)
/** The resource couldn't be allocated because it was already allocated to an instance with exclusive
 *  privileges for the resource */
#define RM_SERVICE_DENIED_RESOURCE_ALLOCATED_TO_INSTANCE_WITH_EXCLUSIVE_PRIV (RM_SERVICE_DENIED_BEGIN+21)
/** End of resource denied reasons */
#define RM_SERVICE_DENIED_END (RM_SERVICE_DENIED_BEGIN+21)

/** RM Service Request Error Code Base */
#define RM_SERVICE_ERROR_BASE (-64)
/** RM service request type not recognized */
#define RM_SERVICE_ERROR_INVALID_SERVICE_TYPE (RM_SERVICE_ERROR_BASE)
/** RM Service request was not provided a component callback
 *  function.  Service requests may result in blocking operations.  A callback
 *  function must always be provided with a service request since
 *  blocked or non-blocked operations cannot be promised.  */
#define RM_SERVICE_ERROR_CALLBACK_NOT_PROVIDED (RM_SERVICE_ERROR_BASE-1)
/** RM service request needs to be forwarded to another RM agent but no transports
 *  have been registered */
#define RM_SERVICE_ERROR_NO_TRANSPORT_REGISTERED (RM_SERVICE_ERROR_BASE-2)
/** RM service request needs to be forwarded but no client delegate or server has 
 *  been registered with the RM instance */
#define RM_SERVICE_ERROR_NOT_REGISTERED_WITH_DEL_OR_SERVER (RM_SERVICE_ERROR_BASE-3)
/** RM service request needs to be forwarded but the transport packet alloc API
 *  has not been provided */
#define RM_SERVICE_ERROR_TRANSPORT_PKT_ALLOC_API_NULL (RM_SERVICE_ERROR_BASE-4)
/** A failure occurred within a registered transport's packet alloc API */
#define RM_SERVICE_ERROR_TRANSPORT_ALLOC_PKT_ERROR (RM_SERVICE_ERROR_BASE-5)
/** RM service request needs to be forwarded but the buffer allocated by transport
 *  is not large enough to fit the RM transport packet */
#define RM_SERVICE_ERROR_TRANSPORT_PKT_BUF_TOO_SMALL (RM_SERVICE_ERROR_BASE-6)
/** RM service request needs to be forwarded but the transport returned an error
 *  when trying to send the RM packet to the higher level agent */
#define RM_SERVICE_ERROR_TRANPSPORT_SEND_ERROR (RM_SERVICE_ERROR_BASE-7)
/** RM service response from higher level agent did not match any requests made
 *  by the provided RM instance */
#define RM_SERVICE_ERROR_TRANSACTION_DOES_NOT_EXIST_FOR_THIS_RM_INSTANCE (RM_SERVICE_ERROR_BASE-8)
/** RM failed to allocate memory for new service transaction */
#define RM_SERVICE_ERROR_TRANSACTION_FAILED_TO_ALLOCATE (RM_SERVICE_ERROR_BASE-9)
/** RM could not find the service transaction in the RM instance's transaction queue */
#define RM_SERVICE_ERROR_SERVICE_TRANSACTION_DOES_NOT_EXIST (RM_SERVICE_ERROR_BASE-10)
/** A failure occurred within a registered transport's packet free API */
#define RM_SERVICE_ERROR_TRANSPORT_FREE_PKT_ERROR (RM_SERVICE_ERROR_BASE-11)
/** Invalid NameServer object modification on non-Server instance */
#define RM_SERVICE_ERROR_NAMESERVER_OBJECT_MOD_ON_INVALID_INSTANCE (RM_SERVICE_ERROR_BASE-12)
/** Request failed because both a NameServer name and a resource range were specified */
#define RM_SERVICE_ERROR_NAMESERVER_NAME_AND_RESOURCE_RANGE_BOTH_DEFINED (RM_SERVICE_ERROR_BASE-13)
/** Error occurred when trying to add an object to the NameServer */
#define RM_SERVICE_ERROR_NAMESERVER_OBJECT_ADD_FAILED (RM_SERVICE_ERROR_BASE-14)
/** Could not find the object specified in the service request in the NameServer */
#define RM_SERVICE_ERROR_NAMESERVER_ERROR_NAME_DOES_NOT_EXIST (RM_SERVICE_ERROR_BASE-15)

/**
 * @brief Maximum number of characters in the resource names
 */
#define RM_RESOURCE_NAME_MAX_CHARS (36)

/** 
 * @brief RM service types
 */
typedef enum {
    /** RM resource allocate for initialization service */
    Rm_service_RESOURCE_ALLOCATE_INIT = 0,
    /** RM resource allocate for use service */
    Rm_service_RESOURCE_ALLOCATE_USE,
    /** RM resource free service */
    Rm_service_RESOURCE_FREE,
    /** RM resource mapping to name service */
    Rm_service_RESOURCE_MAP_TO_NAME,
    /** RM resource get by name service */
    Rm_service_RESOURCE_GET_BY_NAME,
    /** RM resource name unmapping service */
    Rm_service_RESOURCE_UNMAP_NAME
} Rm_ServiceType;

/** 
 * @brief RM pre-main allocation request information provided by the pre-main 
 *        startup function requesting the resource */
typedef struct {
    /** Pointer to the requested pre-main allocation resource name.  The 
     *  name provided by the component must match the resource names
     *  provided in the global resource table and allocation policies */
    char *resourceName;
    /** The pre-main allocation request resource base value.  For example, 
     *  queue number or semaphore number */
    uint32_t resourceBase;
    /** Range of resource starting at resourceBase */
    uint32_t resourceRange;
} Rm_PreMainAllocInfo;

/** 
 * @brief RM service response information provided by RM back to the 
 *        requesting component
 */
typedef struct {
    /** State of the service request.
     *  Non-negative result: RM has taken an action based on the request
     *  Negative result: RM has encountered an error handling the request */
    int32_t serviceState;
    /** A service ID will be returned to the component if the requested service cannot
     *  be completed immediately.  The service ID can be used by the component to identify
     *  service responses received via the component callback function.  A service ID will not
     *  be returned if the service request is satisfied immediately */
    uint32_t serviceId;
    /** The name of the resource affected by the service request */
    char resourceName[RM_RESOURCE_NAME_MAX_CHARS];
    /** The base value of the returned resource.  In the case of a block resource allocation 
     *  response this field will contain the base value of the block. */
    int32_t resourceBase;
    /** The number of resources starting from resourceBase allocated in block requests */
    uint32_t resourceLength;
} Rm_ServiceRespInfo;

/** 
 * @brief RM service callback function structure
 */
typedef struct {
    /** Component callback function.  RM will call this function when the 
     *  resource service request is completed. The callback function supplied
     *  for this parameter must match this function pointer prototype. */
    void (*serviceCallback) (Rm_ServiceRespInfo *serviceResponse);
} Rm_ServiceCallback;

/** 
 * @brief RM service request information provided by the requesting component
 */
typedef struct {
    /** The type of RM service requested */
    Rm_ServiceType type;
    /** Pointer to the name of the resource requested.  The 
     *  name provided by the component must match the resource node names
     *  provided in the global resource table and allocation policies */
    char *resourceName;
/** An allocate service can be requested with an unspecified resource base. 
 *  If this occurs the RM Client Delegate or Server will assign the next available
 *  resource or set of resources based on the allocation type. */
#define RM_RESOURCE_BASE_UNSPECIFIED (-1)  
    /** The resource base value. */
    int32_t resourceBase;
    /** The number of the specified resource to be allocated starting from 
     *  resourceBase.  Will be greater than one only for block allocate
     *  and free service requests. */
    uint32_t resourceLength;
/** An allocate service can be requested with an unspecified resource alignment.
 *  WARNING: Only applicapable if resourceBase is unspecified
 *
 *  If the alignment is unspecified the RM Client Delegate or Server will allocate
 *  the resources from a default alignment as specified in the global policy. */
#define RM_RESOURCE_ALIGNMENT_UNSPECIFIED (-1)      
    /** Resource alignment in block allocation requests */
    int32_t resourceAlignment;
    /** The name server name associated with the resource.  Used only for 
     *  allocate and free by name service requests */
    char *resourceNsName;
    /** Component specified callback function used by RM to inform components
     *  of service requst results */
    Rm_ServiceCallback callback;
} Rm_ServiceReqInfo;

/** 
 * @brief RM Service Port provided to software components and applications that 
 *        request RM services for the resources they wish to use
 */
typedef struct {
    /** RM instance handle for which the service handle was registered */
    void *rmHandle;
    /**
     *  @b Description
     *  @n  
     *      Callout function used by components to request a resource service 
     *      from a RM instance
     *
     *   @param[in] rmHandle
     *      RM instance handle specifying the RM instance that should handle the
     *      service request
     *  
     *  @param[in]  serviceRequest
     *      Service request structure that provides details of the service requested from
     *      the RM instance tied to this component
     *
     *  @param[in]  serviceResponse
     *      Service response structure that provides details of RM's response to the
     *      service request
     */
    void (*rmService)(void *rmHandle, Rm_ServiceReqInfo *serviceRequest,
                      Rm_ServiceRespInfo *serviceResponse);
} Rm_ServicePort;

/**
 *  @b Description
 *  @n  
 *      Non-blocking function used by RTSC pre-main startup functions to
 *      allocate RM resources for usage.  Pre-main allocated resources will be 
 *      validated by RM against a memory-mapped startup resource policy.
 *      Pre-main allocation of unauthorized resources will result in a system
 *      exception.
 *
 *      Note: Resource pre-main allocations can only occur on a core that is 
 *            running a RM Server or Client Delegate that has a startup policy
 *            allowing the allocation of pre-main resources
 *
 *  @param[in]  preMainAllocInfo
 *      Resource pre-main allocation structure that provides details of the 
 *      resource requested from RM for preallocation
 *
 *  @param[out] serviceResponse
 *      Contains the result information regarding the pre-main allocation request
 *
 *  @retval
 *      Success - 0 - Resource pre-main allocation request okay.
 *  @retval
 *      Failure - non-zero - Resource pre-main allocation request error.
 */
void Rm_preMainAllocService (Rm_PreMainAllocInfo *preMainAllocInfo,
                             Rm_ServiceRespInfo *serviceResponse);

/**
 *  @b Description
 *  @n  
 *      This function returns a RM service port to the application to 
 *      provide to software components (LLDs, BIOS, etc) that want to use RM
 *      for resource management.
 *
 *  @param[in]  rmHandle
 *      RM instance handle.  Used to return a Rm_ServicePort from an RM
 *      instance.
 *
 *  @retval
 *      Success - RM Service Port.  Used by an application or component to
 *                request a service from RM.
 *  @retval
 *      Failure - NULL
 */
Rm_ServicePort *Rm_getServicePort(Rm_Handle rmHandle);

/** 
@} 
*/

#ifdef __cplusplus
}
#endif

#endif /* RMSERVICES_H_ */