/** * @file rm.h * * @brief * This is the Resource Manager include file. * * \par * ============================================================================ * @n (C) Copyright 2012-2013, 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_H_ #define RM_H_ #ifdef __cplusplus extern "C" { #endif /* Standard includes */ #include /* RM version */ #include /** @mainpage Resource Manager * * @section intro Introduction * * The Resource Manager low level driver (RM LLD) is designed to provide initialization and permissions checking * */ /* Define RM_API as a master group in Doxygen format and add all RM API definitions to this group. */ /** @defgroup RM_API Resource Manager API * @{ */ /** @} */ /** @defgroup RM_TRANSPORT_API RM Transport-Layer API @ingroup RM_API */ /** @defgroup RM_SERVICES_API RM Registered Component Services API @ingroup RM_API */ /* TODO: CANT CONFLICT WITH OTHER ERROR CODES INCLUDING LIBFDT */ #define RM_INIT_OK 0 #define RM_INIT_ERROR_INSTANCE_NAME_TOO_BIG -256 #define RM_INIT_ERROR_POLICY_NO_VALID_INSTANCES_DEFINED -257 #define RM_INIT_ERROR_POLICY_UNKNOWN_INSTANCE -258 #define RM_INIT_ERROR_POLICY_PERMISSION_SYNTAX_ERROR -259 #define RM_INIT_ERROR_POLICY_UNKNOWN_RESOURCE -260 #define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_MORE_THAN_ONE_INSTANCE_GROUP -261 #define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_MORE_THAN_ONE_ASSIGNMENT_CHAR -262 #define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_INVALID_PERM_CHAR -263 #define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_PERM_CHAR_WITHOUT_ASSIGN_CHAR -264 #define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_INVALID_CHAR_ON_RIGHT_WITH_ASSINMENT_ON_LEFT -265 #define RM_INIT_ERROR_PREMAIN_INST_AND_POSTMAIN_INST_NAMES_DONT_MATCH -266 #define RM_INIT_ERROR_POLICY_UNKNOWN_RESOURCE_PROPERTY -267 #define RM_INIT_ERROR_POLICY_VALID_INSTANCE_NAME_TOO_LONG -268 #define RM_INIT_ERROR_POLICY_SYNTAX_ERROR_INSTANCE_NAME_IN_ASSIGNMENT_TOO_LONG -269 #define RM_INIT_ERROR_NS_ASSIGNMENT_NAME_TOO_LONG -270 #define RM_INIT_ERROR_GRL_INVALID_LINUX_ALIAS_FORMAT -271 #define RM_INIT_ERROR_SERVICE_HANDLE_MEMORY_ALLOC_FAILED -272 #define RM_INIT_ERROR_SERVICE_HANDLE_ALREADY_ALLOCATED -273 #define RM_INIT_ERROR_SERVICE_HANDLE_ALREADY_CLOSED_FOR_INSTANCE -274 /** 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) /** Pre main request was not an allocate use or allocate init request */ #define RM_SERVICE_DENIED_INVALID_PREMAIN_REQUEST (RM_SERVICE_DENIED_BEGIN+22) /** Startup policy denied pre-main allocation request */ #define RM_SERVICE_DENIED_POLICY_DENIED_PREMAIN_ALLOCATION (RM_SERVICE_DENIED_BEGIN+23) /** End of resource denied reasons */ #define RM_SERVICE_DENIED_END (RM_SERVICE_DENIED_BEGIN+23) /** 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) /** RM Transport Result Return Codes */ /** RM Transport Success Code Base */ #define RM_TRANSPORT_OK_BASE (0) /** RM transport action was successful. */ #define RM_TRANSPORT_SUCCESSFUL (RM_TRANSPORT_OK_BASE) /** RM Transport Error Code Base */ #define RM_TRANSPORT_ERROR_BASE (-64) /** RM transport handle has not been registered with the RM instance */ #define RM_TRANSPORT_ERROR_HANDLE_HAS_NOT_BEEN_REGISTERED (RM_TRANSPORT_ERROR_BASE-1) /** RM packets are available but an error was encountered during reception */ #define RM_TRANSPORT_ERROR_PACKET_RECEPTION_ERROR (RM_TRANSPORT_ERROR_BASE-3) /** RM received a packet with an unknown RM packet type */ #define RM_TRANSPORT_ERROR_INVALID_PACKET_TYPE (RM_TRANSPORT_ERROR_BASE-4) /** RM resource request transaction could not be found matching the response received */ #define RM_TRANSPORT_ERROR_MATCHING_RESOURCE_REQUEST_NOT_FOUND (RM_TRANSPORT_ERROR_BASE-5) /** RM NameServer request transaction could not be found matching the response received */ #define RM_TRANSPORT_ERROR_MATCHING_NAME_SERVER_REQUEST_NOT_FOUND (RM_TRANSPORT_ERROR_BASE-6) /** * @brief Maximum number of characters allowed for RM instance, resource, and * NameServer names. */ #define RM_NAME_MAX_CHARS (32) /** * @brief RM Handle provided to application. The RM Handle is used by the * application to distinquish between different RM instances running on * the same core. */ typedef void *Rm_Handle; typedef void *Rm_PreMainHandle; /** * @brief RM Instance types */ typedef enum { /** RM Server */ Rm_instType_SERVER = 0, /** RM Client Delegate */ Rm_instType_CLIENT_DELEGATE = 1, /** RM Client */ Rm_instType_CLIENT = 2 } Rm_InstType; typedef struct { char *instName; Rm_InstType instType; void *startupPolicyDtb; } Rm_PreMainInitCfg; /** * @brief RM instance initialization structure */ typedef struct { /** Pointer to RM instance name character array. The name of the RM instance must * be reflected exactly in the initial RM policies provided to the RM * tree's Servers and Client Delegates. The RM instance name is * used by the policy to map which instances are allowed defined * privileges */ char *instName; /** RM instance type. Defines whether the RM instance will be initialized * as a RM Server, Client Delegate, or Client */ Rm_InstType instType; /** [Server Parameter] Pointer to the device-wide resource list. The list * contains all resources available on the device available for * allocation. Servers running on ARM-Linux cores provide a subset * of the global device list for allocation. The subset is formed from * the global resources leftover after the Linux DTB is parsed for * resources reserved by Linux. * * Note: This parameter will be ignored when the instance type is either * Client Delegate or Client */ void *globalResourceList; /** [Server Parameter When Running on ARM Linux] Pointer to the Linux DTB. * The Linux DTB will be parsed for all tracked resources reserved for use * by Linux. * * Note: This parameter will be ignored when the instance type is either * Client Delegate or Client */ void *linuxDtb; /** [Server/Client Delegate Paramter] Pointer to the allocation * policy. RM Servers should be initialized with the global policy * listing for all RM instances within the system. RM Client Delegates * can be initialized with their local policy, must be a subset of the * global policy provided to the Client Delegate's Server. * * Note: The core charged with the task of initializing the BIOS and IPC * components must run an RM Client Delegate with an initial policy * that allocates a system timer to BIOS and a HW semaphore to IPC * * Note: This parameter will be ignored when the instance type is a * Client */ void *policy; } Rm_InitCfg; /* TESTING PURPOSES: SERVER ONLY */ void Rm_printResourceStatus(Rm_Handle *rmHandle); Rm_PreMainHandle Rm_preMainInit(Rm_PreMainInitCfg *preMainInitCfg, int32_t *result); /** [Server/Client Delegate Parameter] Pre-main allocation handle used to * by application to request resources prior to main via the startup policy * The preMainHandle will be used to validate the resources allocated prior * to main */ int32_t Rm_preMainHandleValidateAndDelete(Rm_Handle rmHandle, Rm_PreMainHandle rmPreMainHandle); /** * @b Description * @n * This function initializes a RM instance. * * IMPORTANT: Rm_init must be called prior to any other component startup * APIs (BIOS_start, Ipc_start, etc). * * @param[in] *initCfg * Pointer to structure containing the initialization information for * this RM instance. * * @param[in] *result * Pointer to a uint32_t that will contain the result of the RM * intialization and handle creation. Any errors encountered will be * returned via this pointer. * * @retval * Success - non-zero Rm_Handle returned. * @retval * Failure - NULL Rm_handle returned. */ Rm_Handle Rm_init(Rm_InitCfg *initCfg, int32_t *result); /** * @b Description * @n * The function is used to get the version information of the RM. * * @retval * Version Information. */ uint32_t Rm_getVersion (void); /** * @b Description * @n * The function is used to get the version string for the RM. * * @retval * Version String. */ const char* Rm_getVersionStr (void); #ifdef __cplusplus } #endif #endif /* RM_H_ */