Completed API documentation and Doxygen
authorJustin Sobota <jsobota@ti.com>
Thu, 7 Feb 2013 00:34:17 +0000 (19:34 -0500)
committerJustin Sobota <jsobota@ti.com>
Thu, 7 Feb 2013 00:34:17 +0000 (19:34 -0500)
18 files changed:
include/rm_dtb_utilloc.h
include/rm_loc.h
include/rm_nameserverloc.h
include/rm_policyloc.h
include/rm_transportloc.h
include/rm_treeloc.h
rm.h
rm_osal.h
rm_transport.h
src/rm.c
src/rm_dtb_util.c
src/rm_nameserver.c
src/rm_policy.c
src/rm_services.c
src/rm_transport.c
src/rm_tree.c
test/rm_osal.c
test/rm_test.c

index 21d0395fd9f8fd5260cdf75eb45c02943a25343d..171b13cb49cc67820b7064b91c8f203bdf25ddb9 100644 (file)
@@ -47,35 +47,32 @@ extern "C" {
 /* RM external includes */
 #include <ti/drv/rm/rm.h>
 
-/** 
-* @brief DTB starting node offset for parsing
-*/
+/* DTB starting node offset for parsing */
 #define RM_DTB_UTIL_STARTING_NODE_OFFSET 0
-/** 
-* @brief DTB starting depth for parsing
-*/
+/* DTB starting depth for parsing */
 #define RM_DTB_UTIL_STARTING_DEPTH 0
-/** 
-* @brief Linux DTB alias offset not set
-*/
-#define RM_DTB_LINUX_ALIAS_OFFSET_NOT_SET 0xFFFF
-/** 
-* @brief Depth of the RM instance nodes in the policy DTB
-*/
-#define RM_POLICY_DTB_INSTANCE_DEPTH 1
+/* Linux DTB alias offset not set */
+#define RM_DTB_UTIL_LINUX_ALIAS_OFFSET_NOT_SET 0xFFFF
 
 /**********************************************************************
  ******************* Common DTB Parsing Definitions *******************
  **********************************************************************/
 
+/* Resource range linked list node */
 typedef struct Rm_ResourceRange_s {
+    /* Resource base */
     uint32_t                   base;
+    /* Resource length */
     uint32_t                   length;
+    /* Link to next resource range linked list node */
     struct Rm_ResourceRange_s *nextRange;
 } Rm_ResourceRange;
 
+/* Resource value linked list node */
 typedef struct Rm_ResourceValue_s {
+    /* Numerical resource value */
     uint32_t                   value;
+    /* Link to next resource value linked list node */
     struct Rm_ResourceValue_s *nextValue;
 } Rm_ResourceValue;
 
@@ -83,6 +80,7 @@ typedef struct Rm_ResourceValue_s {
  ************* Global Resource List Parsing Definitions ***************
  **********************************************************************/
 
+/* GRL resource node property types */
 typedef enum {
     /** Resource DTB unknown property type */
     Rm_resourcePropType_UNKNOWN = 0,  
@@ -94,17 +92,31 @@ typedef enum {
     Rm_resourcePropType_NSASSIGNMENT  
 } Rm_ResourcePropType;
 
+/* Linux alias path linked list node */
 typedef struct Rm_LinuxAlias_s {
+    /* Pointer to the alias path string */
     char                   *path;
+    /* Base value offset into Linux value range located at the end
+     * of the path in the Linux DTB */
     uint32_t                baseOffset;
+    /* Length value offset into the Linux value range located at 
+     * the end of the path in the Linux DTB.  Will be set to
+     * RM_DTB_UTIL_LINUX_ALIAS_OFFSET_NOT_SET if there is only
+     * a base value to read from the Linux DTB */
     uint32_t                lengthOffset;
+    /* Link to next Linux alias linked list node */
     struct Rm_LinuxAlias_s *nextLinuxAlias;
 } Rm_LinuxAlias;
 
+/* NameServer assignment linked list node */
 typedef struct Rm_NsAssignment_s {
+    /* NameServer name to be created */
     char                      nsName[RM_NAME_MAX_CHARS];
+    /* Resource base value to tie to the name */
     uint32_t                  resourceBase;
+    /* Resource length value to tie to the name */
     uint32_t                  resourceLength;
+    /* Link to next NameServer assignment linked list node */
     struct Rm_NsAssignment_s *nextNsAssignment;
 } Rm_NsAssignment;
 
@@ -112,6 +124,7 @@ typedef struct Rm_NsAssignment_s {
  ********************* Policy Parsing Definitions *********************
  **********************************************************************/
 
+/* Policy resource node property types */
 typedef enum {
     /** Policy DTB unknown property type */
     Rm_policyPropType_UNKNOWN = 0,     
@@ -125,15 +138,26 @@ typedef enum {
     Rm_policyPropType_VALID_INSTANCES
 } Rm_PolicyPropType;
 
+/* Policy assignment linked list node */
 typedef struct Rm_PolicyAssignment_s {
+    /* Resource base affected by the permissions */
     uint32_t                      resourceBase;
+    /* Resource length (started from base) affected by the permissions */
     uint32_t                      resourceLength;
+    /* Permissions string defining which RM instances get
+     * which permissions for the defined resource range starting
+     * at resourceBase and ending at
+     * resourceBase+resourceLength-1 */
     char                         *permissionsList;
+    /* Link to next policy assignment linked list node */
     struct Rm_PolicyAssignment_s *nextAssignment;
 } Rm_PolicyAssignment;
 
+/* Valid instance linked list node */
 typedef struct Rm_PolicyValidInst_s {
+    /* RM instance name */
     char                         instName[RM_NAME_MAX_CHARS];
+    /* Link to next valid instance linked list node */
     struct Rm_PolicyValidInst_s *nextValidInst;
 } Rm_PolicyValidInst;
 
@@ -141,8 +165,11 @@ typedef struct Rm_PolicyValidInst_s {
  ******************** Linux DTB Parsing Definitions *******************
  **********************************************************************/
 
+/* Linux value range linked list node */
 typedef struct Rm_LinuxValueRange_s {
+    /* Numerical value extracted from Linux DTB */
     uint32_t                     value;
+    /* Link to next Linux value linked list node */
     struct Rm_LinuxValueRange_s *nextValue;
 } Rm_LinuxValueRange;
 
index 870b7bea5134762574ce3151337eb7d426de055f..b74aa39d0f67956979b0f9de7cbeb3af60dccd40 100644 (file)
@@ -37,8 +37,8 @@
  *  \par
 */
 
-#ifndef RMLOC_H_
-#define RMLOC_H_
+#ifndef RM_LOC_H_
+#define RM_LOC_H_
 
 #ifdef __cplusplus
 extern "C" {
@@ -53,110 +53,147 @@ extern "C" {
 #include <ti/drv/rm/include/rm_nameserverloc.h>
 #include <ti/drv/rm/include/rm_treeloc.h>
 
-/**
- * @brief RM protocol packet resource information
- */
+/* RM resource information */
 typedef struct {
-    /** Resource name of resource affected by command */
+    /* Resource name */
     char     name[RM_NAME_MAX_CHARS];
-    /** If applicable, start of resource range affected by command.  If
-     *  RM_RESOURCE_UNSPECIFIED is assigned the higher level RM agent*/
+    /* Resource base value */
     int32_t  base;
-    /** If applicable, number of specified resource, starting from base, affected by command */
+    /* Resource length value */
     uint32_t length;
-    /** If applicable, the alignment of the resource affected by the command */
+    /* Resource alignment */
     int32_t  alignment;
-    /** If applicable, the NameServer name assigned to the specified
-     *  resource.  Used for commands centering on RM NameServer actions */
+    /* NameServer name tied to resource */
     char     nameServerName[RM_NAME_MAX_CHARS];
 } Rm_ResourceInfo;
 
-/**
- * @brief RM transactions are the internalized version of service requests received 
- *        from components and RM commands received from other RM instances.
- *        Transactions that cannot immediately be serviced are placed in the RM
- *        instance's transaction queue.  The transactions track all service
- *        requests within the RM infrastructure.
- */
+/* Service transaction linked list node */
 typedef struct Rm_Transaction_s {
-    /** Transaction service type */
-    Rm_ServiceType type;
-    /** Local ID of the transaction. */
-    uint32_t localId;
-    /** ID of transaction in RM instance that generated the
-     *  packet that resulted in the creation of the transaction.  The
-     *  originating ID will be placed in the transaction's response packet
-     *  to the lower level RM instance.  The lower level RM instance will 
-     *  match the response packet with the originating request using the ID */
-    uint32_t remoteOriginatingId;
-    /** Name of the RM instance the RM packet, that spawned the transaction,
-     *  originated from */
-    char pktSrcInstName[RM_NAME_MAX_CHARS];
-    /** Transaction's associated callback function */
-    Rm_ServiceCallback callback;
-    /** Transaction state.  The codes are externally visible and tracked
-     *  in rmservices.h */
-    int32_t state;
-    /** Transaction has been forwarded to CD or Server instance.  Waiting for response */
-    bool hasBeenForwarded;
-    /** Name of the RM instance the service originated from */
-    char serviceSrcInstName[RM_NAME_MAX_CHARS];    
-    /** Resource information */
-    Rm_ResourceInfo resourceInfo;
-    /** Link to the next transaction in the queue */
+    /* Transaction service type */
+    Rm_ServiceType           type;
+    /* Local ID of the transaction. */
+    uint32_t                 localId;
+    /* ID of transaction in RM instance that generated the
+     * packet that resulted in the creation of the transaction.  The
+     * originating ID will be placed in the transaction's response packet
+     * The RM instance that receives the response will 
+     * match the response packet with the originating request using the ID */
+    uint32_t                 remoteOriginatingId;
+    /* Name of the RM instance that generated the packet that resulted
+     * in the creation of the service transaction.  Used to send the response
+     * packet. */
+    char                     pktSrcInstName[RM_NAME_MAX_CHARS];
+    /* Transaction service callback function */
+    Rm_ServiceCallback       callback;
+    /* Transaction state.  The codes are defined in rm.h */
+    int32_t                  state;
+    /* Transaction has been forwarded to CD or Server instance.  Waiting for response */
+    bool                     hasBeenForwarded;
+    /* Name of the RM instance the service originated from */
+    char                     serviceSrcInstName[RM_NAME_MAX_CHARS];    
+    /* Resource information */
+    Rm_ResourceInfo          resourceInfo;
+    /* Link to the next transaction in the queue */
     struct Rm_Transaction_s *nextTransaction;    
 } Rm_Transaction;
 
+/* Resource properties extracted from the GRL DTB */
 typedef struct {
+    /* Pointer to a resource's range data within the GRL DTB */
     const void *rangeData;
+    /* Length in bytes of a resource's range data in the GRL DTB */
     int32_t     rangeLen;
+    /* Pointer to a resource's NameServer assignment data within the GRL DTB.
+     * Will be NULL if not defined for the resource node. */
     const void *nsAssignData;
+    /* Length in bytes of a resource's NameServer assignment data in the GRL DTB.
+     * Will be zero if not defined for the resource node. */
     int32_t     nsAssignLen;
+    /* Pointer to a resource's Linux alias data within the GRL DTB.  Will be
+     * NULL if not defined for the resource node. */
     const void *linuxAliasData;
+    /* Length in bytes of a resource's Linux alias data data in the GRL DTB.
+     * Will be zero if not defined for the resource node. */
     int32_t     linuxAliasLen;
 } Rm_ResourceProperties;
 
+/* Resource allocator operations */
 typedef enum {
+    /* Allocate operation */
     Rm_allocatorOp_ALLOCATE = 0,
+    /* Free operation */
     Rm_allocatorOp_FREE,
+    /* Preallocate based on Policy DTB information operation */
     Rm_allocatorOp_PRE_ALLOCATE
 } Rm_AllocatorOp;
 
+/* Allocator operation configuration structure */
 typedef struct {
+    /* RM instance for which the allocator operation is taking place */
     Rm_PolicyValidInstNode *serviceSrcInstNode;
+    /* Allocator operation type */
     Rm_AllocatorOp          operation;
+    /* Specifies the type of allocation
+     * a) Allocate to initialize
+     * b) Allocate to use */
     uint32_t                allocType;
+    /* Resources for which the allocator operation will affect */
     Rm_ResourceInfo        *resourceInfo;
 } Rm_AllocatorOpInfo;
 
+/* RM allocator linked list node */
 typedef struct Rm_Allocator_s {
+    /* Resource name for which the allocator was created.  The resource name
+     * must match a resource node defined in both the GRL and the Policy */
     char                   resourceName[RM_NAME_MAX_CHARS];
-    /** Pointer to the first resource entry in the allocator */
+    /* Pointer to the root entry of the allocator tree */
     void                  *allocatorRootEntry;
-    /** Pointer to next resource allocator */
+    /* Pointer to next resource allocator node */
     struct Rm_Allocator_s *nextAllocator;
 } Rm_Allocator;
 
+/* Static policy information */
 typedef struct {
+    /* Pointer to the static policy if provided */
     void                   *staticPolicy;
+    /* Pointer to the root entry of the valid instance tree
+     * extracted from the static policy */
     Rm_PolicyValidInstTree *staticValidInstTree;
 } Rm_StaticInfo;
 
+/* RM instance structure */
 typedef struct {
+    /* Name given to the RM instance.  Policy will assign resources based
+     * on the names assigned to instances at instance init */
     char                    instName[RM_NAME_MAX_CHARS];
+    /* Instance type */
     Rm_InstType             instType;
-    /* Instance locks if static request fails when checked against global policy */
+    /* Instance lock status.  Instance locks if static request fails when
+     * checked against global policy */
     bool                    isLocked;
+    /* Pointer to the serviceHandle opened from the instance */
     Rm_ServiceHandle       *serviceHandle;
+    /* Tracks whether the instance has registered with a CD or Server.
+     * Applicable to CD and Client instances */
     bool                    registeredWithDelegateOrServer;
-    void                   *policy;
-    Rm_PolicyValidInstTree *validInstances;    
-    Rm_Allocator           *allocators;
-    Rm_NameServerTree      *nameServer;
+    /* Linked list of transports registered by the application */
     void                   *transports;
+    /* Service transaction sequence number tracker */
     uint32_t                transactionSeqNum;
+    /* Service transaction linked list queue */
     Rm_Transaction         *transactionQueue;
+    /* Transport callout functions provided by application during transport
+     * registration */
     Rm_TransportCallouts    transportCallouts;
+    /* [Server] Pointer to the global policy */
+    void                   *policy;
+    /* [Server] Pointer to root entry of the global policy valid instance tree */
+    Rm_PolicyValidInstTree *validInstances;
+    /* [Server] Pointer to the linked list of allocators */
+    Rm_Allocator           *allocators;
+    /* [Server] Pointer to the root entry of the NameServer */
+    Rm_NameServerTree      *nameServer;    
+    /* [CD or Client] Static policy data */
     Rm_StaticInfo           staticInfo;
 } Rm_Inst;
 
@@ -170,5 +207,5 @@ void rmTransactionProcessor (Rm_Inst *rmInst, Rm_Transaction *transaction);
 }
 #endif
 
-#endif /* RMLOC_H_ */
+#endif /* RM_LOC_H_ */
 
index 5d94b0b75129939eebedde1e6ca189c907ce6df7..845cb45f3400aa99a4eecd6c3734088dc4d2952f 100644 (file)
@@ -51,8 +51,11 @@ extern "C" {
  ********************* Internal NameServer APIs ***********************
  **********************************************************************/
 
+/* NameServer configuration structure */
 typedef struct {
+    /* Pointer to the root entry of the NameServer tree structure */
     Rm_NameServerTree    *nameServerTree;
+    /* NameServer tree node configuration struction */
     Rm_NameServerNodeCfg  nodeCfg;
 } Rm_NameServerObjCfg;
 
index dc7fbf9daf4dba4e30b32364b6b93bebbe3050a6..a89a9f9ed584b5e63c1f6a4f376b71175ec0b5d2 100644 (file)
@@ -1,7 +1,7 @@
 /*
  *  file  rm_policyloc.h
  *
- *  Prototypes and data structures for the Resource Manager Policies.
+ *  Internal prototypes and data structures for the Resource Manager Policies.
  *
  *  ============================================================================
  *      (C) Copyright 2012-2013, Texas Instruments, Inc.
@@ -50,71 +50,98 @@ extern "C" {
 /* RM internal includes */
 #include <ti/drv/rm/include/rm_treeloc.h>
 
-/** String stored for resource elements that are reserved by the Linux kernel.  These
- *  resources will be in use for the lifetime of the system 
+/* String stored for resource elements that are reserved by the Linux kernel.  These
+ * resources will be in use for the lifetime of the system 
  *
- * TODO: MOVE TO policy.h LATER SO INTEGRATORS KNOW NOT TO NAME RM INSTANCES THIS NAME*/
+ * TODO: MOVE TO policy.h LATER SO INTEGRATORS KNOW NOT TO NAME RM INSTANCES THIS NAME */
 #define RM_ALLOCATED_TO_LINUX "Linux-Kernel"
 
-/* Bit : Description
+/* Policy permission bit storage type
+ * Bit : Description
  *-----------------------------
- *  0  : Init         (iI) - RM instance has initialization permission for resource
- *  1  : Use          (uU) - RM instance has usage permission for resource
- *  2  : Exclusive    (xX) - RM instance has exclusive allocation privilege for resource
- *                           i.e. No other RM instance can reserve the resource if a RM
- *                           instance with exclusive privilege reserves the resource
- *  3  : Shared Linux (sS) - Resource has been reserved by the Linux kernel but can be
- *                           allocated by the specified RM instances
+ *  0  : Init         (i) - RM instance has initialization permission for resource
+ *  1  : Use          (u) - RM instance has usage permission for resource
+ *  2  : Exclusive    (x) - RM instance has exclusive allocation privilege for resource
+ *                          i.e. No other RM instance can reserve the resource if a RM
+ *                          instance with exclusive privilege reserves the resource
+ *  3  : Shared Linux (s) - Resource has been reserved by the Linux kernel but can be
+ *                          allocated by the specified RM instances (NOT IMPLEMENTED YET)
  *  4 - 15 : UNUSED
  */
 typedef uint16_t Rm_PolicyPermBits;
 
+/* Initialization permission characters */
 #define RM_POLICY_PERM_INIT_LOWER         'i'
 #define RM_POLICY_PERM_INIT_UPPER         'I'
+/* Initialization permission bit shift */
 #define RM_POLICY_PERM_INIT_SHIFT          0
+/* Usage permission characters */
 #define RM_POLICY_PERM_USE_LOWER          'u'
 #define RM_POLICY_PERM_USE_UPPER          'U'
+/* Usage permission bit shift */
 #define RM_POLICY_PERM_USE_SHIFT           1
+/* Exclusive permission characters */
 #define RM_POLICY_PERM_EXCLUSIVE_LOWER    'x'
 #define RM_POLICY_PERM_EXCLUSIVE_UPPER    'X'
+/* Exclusive permission bit shift */
 #define RM_POLICY_PERM_EXCLUSIVE_SHIFT     2
+/* Shared Linux permission characters */
 #define RM_POLICY_PERM_SHARED_LINUX_LOWER 's'
 #define RM_POLICY_PERM_SHARED_LINUX_UPPER 'S'
+/* Shared Linux permission bit shift */
 #define RM_POLICY_PERM_SHARED_LINUX_SHIFT  3
 
+/* Permissions subgroup start character */
 #define RM_POLICY_PERM_SUBGROUP_START     '('
+/* Permissions subgroup end character */
 #define RM_POLICY_PERM_SUBGROUP_END       ')'
+/* Permissions subgroup terminator */
 #define RM_POLICY_PERM_TERMINATOR         '&'
+/* Permissions assignment character */
 #define RM_POLICY_PERM_ASSIGNMENT         '='
 
+/* Macro to set permissions in a Rm_PolicyPermBits type */
 #define RM_policy_SET_PERM(permBits, permTypeShift, val) \
     permBits = ((permBits & (~(((Rm_PolicyPermBits) 0x1) << permTypeShift))) | \
                ((((Rm_PolicyPermBits) val) & 0x1) << permTypeShift))
+/* Macro to get permissions from Rm_PolicyPermBits type */               
 #define RM_policy_GET_PERM(permBits, permTypeShift) \
     ((permBits >> permTypeShift) & 0x1)
 
+/* Assigned instance permissions linked list node */
 typedef struct Rm_Permission_s {
+    /* Instance name of instance assigned the permissions */
     char                    instName[RM_NAME_MAX_CHARS];
+    /* Permissions assigned to the RM instance with instName */
     Rm_PolicyPermBits       permissionBits;
+    /* Next permissions node */
     struct Rm_Permission_s *nextPermission;
 } Rm_PolicyPermission;
 
-/**********************************************************************
- *********************** Internal Policy APIs *************************
- **********************************************************************/
-
+/* Permission validation types */
 typedef enum {
+    /* Validate exclusive permissions for a resource */
     Rm_policyCheck_EXCLUSIVE = 0,
+    /* Validate initialization permissions for a resource */
     Rm_policyCheck_INIT,
+    /* Validate usage permissions for a resource */
     Rm_policyCheck_USE
 } Rm_PolicyCheckType;
 
+/* Permissions validation configuration structure */
 typedef struct {
+    /* The type of validation to perform */
     Rm_PolicyCheckType      type;
+    /* Policy to validate the permission check against */
     void                   *policyDtb;
+    /* Valid instance node that will have its permissions checked for 
+     * the defined resource */
     Rm_PolicyValidInstNode *validInstNode;
+    /* Resource node offset in the policy DTB */
     int32_t                 resourceOffset;
+    /* Resource base to validate permissions for the valid instance node */
     uint32_t                resourceBase;
+    /* Resource length to validate permissions for the valid instance node */
     uint32_t                resourceLength;
 } Rm_PolicyCheckCfg;
 
index 85c120ecb26d9b08f83de49f7fe2c21f4e97e86f..8ea1c6deac38496d223fe5beb94cae06df9a4074 100644 (file)
@@ -70,21 +70,17 @@ extern "C" {
     RM_COMPILE_TIME_SIZE_CHECK(RM_TRANSPORT_PACKET_MAX_SIZE_BYTES >= sizeof(Rm_NsRequestPkt)); \
     RM_COMPILE_TIME_SIZE_CHECK(RM_TRANSPORT_PACKET_MAX_SIZE_BYTES >= sizeof(Rm_NsResponsePkt)); \
 
-/**
- * @brief RM transport routing map linked list node.  The created 
- *        transport nodes are provided to the application casted
- *        as a Rm_TransportHandle
- */
+/* RM transport list node */
 typedef struct Rm_Transport_s {
-    /** The RM instance that this node belongs to */
+    /* RM instance this node was registered to */
     Rm_Handle              rmHandle;
-    /** The application transport handle */
+    /* Application transport handle provided by application */
     Rm_AppTransportHandle  appTransportHandle;
-    /** The remote RM instance type */
+    /* Remote RM instance type */
     Rm_InstType            remoteInstType;
-    /** The remote RM instance name */
+    /* Remote RM instance name */
     char                   remoteInstName[RM_NAME_MAX_CHARS];
-    /** Link to the next route node in the route map list */
+    /* Link to next transport node */
     struct Rm_Transport_s *nextTransport;
 } Rm_Transport;
 
@@ -92,98 +88,86 @@ typedef struct Rm_Transport_s {
  ************************* RM Packet Defs *****************************
  **********************************************************************/
 
-/** 
- * @brief Resource Request Packet Types
- */
+/* Resource Request Packet Types */
 typedef enum {
-    /** Resource allocate for init request */
+    /* Resource allocate for init request */
     Rm_resReqPktType_ALLOCATE_INIT = 0,
-    /** Resource allocate for use request */
+    /* Resource allocate for use request */
     Rm_resReqPktType_ALLOCATE_USE,
-    /** Free resource */
+    /* Free resource */
     Rm_resReqPktType_FREE,
-    /** Get name resource */
+    /* Get name resource */
     Rm_resReqPktType_GET_NAMED
 } Rm_ResourceReqPktType;
 
-/** 
- * @brief Resource Request Packet - Packet sent to higher level RM agents to request
- *        a resource service that cannot be handled on the local RM instance due to 
- *        permission restrictions.
- */
+/* Resource Request Packet - Packet sent to CDs and Servers to request
+ * a resource service that cannot be handled on the local RM instance due to 
+ * permission restrictions. */
 typedef struct {
-    /** The transaction ID associated with the request packet */
+    /* Transaction ID associated with the request packet */
     uint32_t              requestId;  
-    /** The resource request type */
+    /* Resource request type */
     Rm_ResourceReqPktType resourceReqType;
-    /** RM instance name from which the request packet originated.  Used by 
-     *  receiving instance to route the response */
+    /* RM instance name from which the request packet originated.  Used by 
+     * receiving instance to route the response */
     char                  pktSrcInstName[RM_NAME_MAX_CHARS];    
-    /** Name of RM instance that is issuing the service request. The instance 
-     *  name will be used to validate the request against the RM policy defined
-     *  for the instance. */
+    /* Name of RM instance that is issuing the service request. The instance 
+     * name will be used to validate the request against the RM policy defined
+     * for the instance. */
     char                  serviceSrcInstName[RM_NAME_MAX_CHARS];      
-    /** Resource request information */
+    /* Resource request information */
     Rm_ResourceInfo       resourceInfo;
 } Rm_ResourceRequestPkt;
 
-/** 
- * @brief Resource Response Packet - Packet sent to RM instances that requested
- *        a resource service from a higher level RM agent.  The packet will contain
- *        resource response information based on the request
- */
+/* Resource Response Packet - Packet sent to RM instances that requested
+ * a resource service.  The packet will contain resource response 
+ * information based on the request */
 typedef struct {
-    /** responseID will equal the requestId received in the resource request
-     *  packet.  This ID should be associated with a transaction stored in 
-     *  the RM instance that sent the resource request packet */
+    /* responseID will equal the requestId received in the resource request
+     * packet.  This ID should be associated with a transaction stored in 
+     * the RM instance that sent the resource request packet */
     uint32_t        responseId;
-    /** State of the request.  Resource request denied, or error.  The
-     *  return values are externally visible so they're tracked in rmservice.h */
+    /* State of the request.  Resource request denied, or error.  The
+     * return values are externally visible in rm.h */
     int32_t         requestState;
     /* Resource response information */
     Rm_ResourceInfo resourceInfo;
 } Rm_ResourceResponsePkt;
 
-/** 
- * @brief NameServer Request Packet Types
- */
+/* NameServer Request Packet Types */
 typedef enum {
-    /** Request to map the specified name to the specified resources */
+    /* Request to map the specified name to the specified resources */
     Rm_nsReqPktType_MAP_RESOURCE = 0,
-    /** Request to unmap the specified name from the specifed resources */
+    /* Request to unmap the specified name from the specifed resources */
     Rm_nsReqPktType_UNMAP_RESOURCE
 } Rm_NsReqPktType;
 
-/** 
- * @brief NameServer Request Packet - Packet sent by RM instances containing
- *        NameServer mapping or unmapping data
- */
+/* NameServer Request Packet - Packet sent by RM instances containing
+ * NameServer mapping or unmapping data */
 typedef struct {
-    /** The transaction ID associated with the request packet */
+    /* Transaction ID associated with the NameServer request packet */
     uint32_t        requestId;  
-    /** The resource request type */
+    /* NameServer request type */
     Rm_NsReqPktType nsRequestType;
-    /** RM instance name from which the request packet originated.  Used by 
-     *  receiving instance to route the response */
+    /* RM instance name from which the request packet originated.  Used by 
+     * receiving instance to route the response */
     char            pktSrcInstName[RM_NAME_MAX_CHARS];
-    /** RM instance name making the service request.  Policies may restrict who
-     *  can and cannot map and unmap resources via the RM NameServer */
+    /* RM instance name making the service request.  Policies may restrict who
+     * can and cannot map and unmap resources via the RM NameServer */
     char            serviceSrcInstName[RM_NAME_MAX_CHARS];
-    /** Resource request information */
+    /* Resource request information */
     Rm_ResourceInfo resourceInfo;
 } Rm_NsRequestPkt;
 
-/** 
- * @brief NameServer Response Packet - Provides NameServer transaction response
- *        data to RM instances that request a name map or unmap
- */
+/* NameServer Response Packet - Provides NameServer transaction response
+ * data to RM instances that request a name map or unmap */
 typedef struct {
-    /** responseID will equal the requestId received in the resource request
-     *  packet.  This ID should be associated with a transaction stored in 
-     *  the RM instance that sent the resource request packet */
+    /* responseID will equal the requestId received in the NameServer request
+     * packet.  This ID should be associated with a transaction stored in 
+     * the RM instance that sent the resource request packet */
     uint32_t responseId;
-    /** State of the request.  Resource request denied, or error.  The
-     *  return values are externally visible so they're tracked in rmservice.h */
+    /* State of the request.  Resource request denied, or error.  The
+     * return values are externally visible in rm.h */
     int32_t  requestState;
 } Rm_NsResponsePkt;
 
index a8e4c619afba9a65978f8fc0bb6eedc88ed642d8..5ef078cfcc2ccacac7e3b2687513dc0694f34ace 100644 (file)
@@ -58,45 +58,82 @@ extern "C" {
  *************** Tree Node Data Structure Definitions *****************
  **********************************************************************/
 
+/* NameServer node configuration structure */
 typedef struct {
+    /* Name to assign to the resource values */
     char     *objName;
+    /* Resource name assigned to the NameServer name */
     char     *resourceName;
+    /* Resource base value assigned to the NameServer name */    
     uint32_t  resourceBase;
+    /* Resource length value (starting from base) assigned to the NameServer name */    
     uint32_t  resourceLength;
 } Rm_NameServerNodeCfg;
 
+/* NameServer node */
 typedef struct _Rm_NameServerNode {
+    /* Tree algorithm data structure */
     RB_ENTRY(_Rm_NameServerNode) linkage;
+    /* Name string */
     char                         objName[RM_NAME_MAX_CHARS];
+    /* Resource name */
     char                         resourceName[RM_NAME_MAX_CHARS];
+    /* Resource base value */
     uint32_t                     resourceBase;
+    /* Resource length value */
     uint32_t                     resourceLength;
 } Rm_NameServerNode;
 
+/* NameServer tree root entry type definition */
 typedef RB_HEAD(_Rm_NameServerTree, _Rm_NameServerNode) Rm_NameServerTree;
 
+/* Valid instance node */
 typedef struct _Rm_PolicyValidInstNode {
+    /* Tree algorithm data structure */
     RB_ENTRY(_Rm_PolicyValidInstNode) linkage;
+    /* Valid instance name string */
     char                              name[RM_NAME_MAX_CHARS];
+    /* Number of existing resource allocations the instance is
+     * reference in.  Resource frees involving the instance
+     * will decrement this count.  A valid instance node cannot
+     * be deleted until this value is zero */
     uint32_t                          allocRefCount;
+    /* TRUE: Delete this valid instance node once the allocRefCount
+     *       reaches zero
+     * FALSE: Do not delete */
     bool                              deletePending;
 } Rm_PolicyValidInstNode;
 
+/* Valid instance tree root entry type definition */
 typedef RB_HEAD(_Rm_PolicyValidInstTree, _Rm_PolicyValidInstNode) Rm_PolicyValidInstTree;
 
+/* Resource node owner linked list node */
 typedef struct Rm_Owner_s {
-    Rm_PolicyValidInstNode  *instNameNode;
-    struct Rm_Owner_s *nextOwner;
+    /* Pointer to the valid instance node that currently
+     * owns or partially owns the resource */
+    Rm_PolicyValidInstNode *instNameNode;
+    /* Link to the next owner of the resoruce if the resource is shared */
+    struct Rm_Owner_s      *nextOwner;
 } Rm_Owner;
 
+/* Resource node */
 typedef struct _Rm_ResourceNode {
-    RB_ENTRY(_Rm_ResourceNode)  linkage;
-    uint32_t                    base;
-    uint32_t                    length;
-    uint16_t                    allocationCount;
-    Rm_Owner                    *ownerList;
+    /* Tree algorithm data structure */
+    RB_ENTRY(_Rm_ResourceNode) linkage;
+    /* Resource base value */
+    uint32_t                   base;
+    /* Resource length value.  With base this node covers a resource's values
+     * from base to base+length-1 */
+    uint32_t                   length;
+    /* Number of times this resource node has been allocated to a valid
+     * instance.  This value will decrement for each free operation */
+    uint16_t                   allocationCount;
+    /* Linked list of existing owners.  Will be NULL if no owners exist
+     * for the resource node */
+    Rm_Owner                   *ownerList;
 } Rm_ResourceNode;
 
+/* Resource tree root entry type definition */
 typedef RB_HEAD(_Rm_AllocatorResourceTree, _Rm_ResourceNode) Rm_ResourceTree;
 
 /**********************************************************************
@@ -127,5 +164,5 @@ RB_PROTOTYPE(_Rm_AllocatorResourceTree, _Rm_ResourceNode, linkage, rmResourceNod
 }
 #endif
 
-#endif /* RM_NAMESERVERLOC_H_ */
+#endif /* RM_TREELOC_H_ */
 
diff --git a/rm.h b/rm.h
index 4e277c7519178dc2b418fca9fef3d2d8b9c946b2..0a14033f12460de03438982e70d185a141c5d197 100644 (file)
--- a/rm.h
+++ b/rm.h
@@ -232,6 +232,10 @@ extern "C" {
 #define RM_ERROR_INVALID_INST_TYPE                 RM_ERROR_BASE-40
 /** Linux DTB alias properties specified in GRL but no Linux DTB provided during server instance init */
 #define RM_ERROR_GRL_LINUX_ALIAS_BUT_NO_DTB        RM_ERROR_BASE-41
+/** RM attempted to allocate a transport packet but the rmAllocPkt callout was not registered */
+#define RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD      RM_ERROR_BASE-42
+/** RM attempted to send a packet but the rmSendPkt callout was not registered */
+#define RM_ERROR_TRANSPORT_SEND_NOT_REGD           RM_ERROR_BASE-43
 
 /** 
  * @brief Maximum number of characters allowed for RM instance, resource, and
@@ -345,6 +349,21 @@ typedef struct {
  */
 void Rm_printResourceStatus(Rm_Handle rmServerHandle);
 
+/**
+ *  @b Description
+ *  @n  
+ *      This function prints the current status of a RM instance.  The
+ *      following instance properties will be printed:
+ *      a) instance name & type
+ *      b) The instance's registered transports 
+ *      c) All service transactions queued in the instance transaction
+ *         queue and their states
+ *
+ *  @param[in]  rmHandle
+ *      Instance handle.
+ */
+void Rm_printInstanceStatus(Rm_Handle rmHandle);
+
 /**
  *  @b Description
  *  @n  
index 6bf8bde7b863857313fecb1e24df7b776daf92df..dec997e6c37ba9bd4cff6bed4fcc2a29d0a7e685 100644 (file)
--- a/rm_osal.h
+++ b/rm_osal.h
@@ -2,8 +2,8 @@
  *   @file  rm_osal.h
  *
  *   @brief   
- *      This is the sample OS Adaptation layer which is used by the RM low level
- *      driver. The OSAL layer can be ported in either of the following 
+ *      This is the sample OS Adaptation layer which is used by the Resource
+ *      Manager. The OSAL layer can be ported in either of the following 
  *      manners to a native OS:
  *
  *      <b> Approach 1: </b>
@@ -64,8 +64,8 @@
  *
  *  \par
 */
-#ifndef __RM_OSAL_H__
-#define __RM_OSAL_H__
+#ifndef RM_OSAL_H_
+#define RM_OSAL_H_
 
 /** @addtogroup RM_OSAL_API
  @{ 
@@ -80,8 +80,8 @@ extern void Osal_rmFree (void *ptr, uint32_t size);
 extern void Osal_rmLog (char *fmt, ... );
 
 /**
- * @brief   The macro is used by the RM LLD to allocate memory of specified
- * size
+ * @brief   The macro is used by RM to allocate memory of specified
+ *          size
  *
  * <b> Prototype: </b>
  *  The following is the C prototype for the expected OSAL API.
@@ -93,18 +93,14 @@ extern void Osal_rmLog (char *fmt, ... );
  *  <b> Parameter </b>
  *  @n  Number of bytes to be allocated
  *
- *  <b> Parameter </b>
- *  @n  If true the memory should could from shared memory
- *
  *  <b> Return Value </b>
  *  @n  Pointer to the allocated block size
  */
-
 #define Rm_osalMalloc             Osal_rmMalloc
 
 /**
- * @brief   The macro is used by the RM LLD to free a allocated block of 
- * memory 
+ * @brief   The macro is used by RM to free a allocated block of 
+ *          memory 
  *
  * <b> Prototype: </b>
  *  The following is the C prototype for the expected OSAL API.
@@ -120,12 +116,11 @@ extern void Osal_rmLog (char *fmt, ... );
  *  <b> Return Value </b>
  *  @n  Not applicable.
  */
-
 #define Rm_osalFree               Osal_rmFree
 
 /**
- * @brief   The macro is used by the RM LLD to log various 
- * messages. 
+ * @brief   The macro is used by RM to log various 
+ *          messages. 
  *
  * <b> Prototype: </b>
  *  The following is the C prototype for the expected OSAL API.
@@ -145,5 +140,6 @@ extern void Osal_rmLog (char *fmt, ... );
 /**
 @}
 */
-#endif /* __RM_OSAL_H__ */
+
+#endif /* RM_OSAL_H_ */
 
index fc42ca7cf752be7999f8ab00148148fdd166191d..e97e8f6dc6ea49037272a37d94f2b7eb157cd42d 100644 (file)
@@ -2,8 +2,8 @@
  *   @file  rm_transport.h
  *
  *   @brief   
- *      This is the RM include file for the generic transport interface used by RM to exchange
- *      RM control signals and data between RM instances
+ *      This is the RM include file for the generic transport interface 
+ *      used by RM to exchange RM control signals and data between RM instances
  *
  *  \par
  *  ============================================================================
@@ -58,7 +58,9 @@ extern "C" {
 @{
 */
 
-/** Maximum size of the RM transport packet */
+/**
+ * @brief Maximum size of RM transport packet 
+ */
 #define RM_TRANSPORT_PACKET_MAX_SIZE_BYTES (256)
 
 /** 
@@ -67,14 +69,28 @@ extern "C" {
 typedef void *Rm_TransportHandle;
 
 /**
- * @brief Application transport handle
+ * @brief Application transport handle.  Void casted application transport
+ *        data structure.  The Rm_AppTransportHandle provided by the
+ *        application could be anything from a queue number to a pointer
+ *        to an application transport data structure.  RM will provide
+ *        a Rm_AppTransportHandle to the application any time RM 
+ *        wants to alloc or send a packet via the transport callouts
  */
 typedef void *Rm_AppTransportHandle; 
 
+/**
+ * @brief A void pointer to the start of a registered application transport
+ *        packet buffer.  The Rm_PacketHandle may be different from the 
+ *        rm_Packet pointer based on the application transport.  For example,
+ *        for a QMSS based transport the Rm_PacketHandle may point to the
+ *        beginning of a Host descriptor where as the Rm_Packet pointer would
+ *        point to the beginning of the data buffer linked with the Host
+ *        descriptor.
+ */
 typedef void *Rm_PacketHandle;
 
 /**
- * @brief RM packet types that can be sent between RM instances
+ * @brief RM packet types
  */
 typedef enum {
     /** Allocate/Free request packet */
@@ -93,58 +109,85 @@ typedef enum {
 typedef struct {
     /** Packet length in bytes.  Written by application when allocated */
     uint32_t   pktLenBytes;
-    /** Type of RM packet contained in the byte data array */
+    /** Type of RM packet contained in data byte array */
     Rm_pktType pktType;
     /** Byte array containing RM packet data */
     char       data[RM_TRANSPORT_PACKET_MAX_SIZE_BYTES];
 } Rm_Packet;
 
+/** 
+ * @brief RM transport callout functions used by RM to allocate and send
+ *        RM packets via the application data paths between RM instances
+ */
 typedef struct {
     /**
      *  @b Description
      *  @n  
      *      This function pointer describes the RM transport layer packet 
-     *      allocation function.  The application which integrates with RM must 
-     *      supply a function to RM at initialization time that matches this  
-     *      prototype.  The provided function implements the allocation of packet
-     *      buffers for use by the RM transport for sending messages between RM
-     *      instances in the SOC.
+     *      allocation function.  The application must supply an alloc function
+     *      to RM instances at transport registration if the RM instance is 
+     *      intended to communicate with other RM instances.  The function
+     *      provided by the application must match this prototype.  The provided
+     *      function implements the allocation of packet buffers from the 
+     *      application data path that the RM transport will use to send messages
+     *      between RM instances.  The Rm_Packet pointer will point to start of
+     *      the data buffer containing the RM packet data.  The pktHandle will
+     *      point to the start of the application data path "packet" data
+     *      structure.  The Rm_Packet pointer and pktHandle cannot be NULL.  They
+     *      will either be different or the same value based on the application
+     *      transport.
      *
-     *  @param[in]  transportHandle
-     *      Which application transport to allocate a packet from.
+     *  @param[in]  appTransport
+     *      Application transport handle to allocate packet from.  This value
+     *      is provided by the application at transport registration.
      *
      *  @param[in]  pktSize
-     *      Size of requested packet allocation.
+     *      Size of buffer needed by RM for the RM packet.  The application
+     *      must place this value in the pktLenBytes field of the Rm_Packet.
+     *      after the buffer has been allocated.
+     *
+     *  @param[out]  pktHandle
+     *      Pointer to the start of the application's transport "packet".
+     *      Could be the pointer to the start of a QMSS descriptor,
+     *      network packet, etc.
      *
      *  @retval
      *      Success - Pointer to allocated packet buffer.
      *  @retval
      *      Failure - NULL
      */
-
-    /* Rm_Packet * and pktHandle cannot be NULL.  They will either be different or the same
-     * value based on the transport */
     Rm_Packet *(*rmAllocPkt)(Rm_AppTransportHandle appTransport, uint32_t pktSize, 
                              Rm_PacketHandle *pktHandle);    
     /**
      *  @b Description
      *  @n  
-     *      This function pointer describes the RM transport layer send function.
-     *      The application which integrates with RM must supply a function to RM
-     *      at initialization time that matches this prototype.  The provided 
-     *      function implements the send side of the transport between RM 
-     *      instances on different cores in the SOC.
+     *      This function pointer describes the RM transport layer packet 
+     *      send function.  The application must supply a send function
+     *      to RM instances at transport registration if the RM instance is 
+     *      intended to communicate with other RM instances.  The function
+     *      provided by the application must match this prototype.  The provided
+     *      function implements the sending of application data path packets,
+     *      encapsulating RM packets, between RM instances.  The pktHandle will
+     *      point to the start of the application data path "packet" data
+     *      structure.
      *
-     *  @param[in]  transportHandle
-     *      Which application transport to send the packet over.
+     *      RM assumes that the application will free application data
+     *      path packet and the buffer containing the Rm_Packet after
+     *      the send operation.
      *
-     *  @param[in]  pkt
-     *      Pointer to resource packet to be sent to the destination RM.
+     *  @param[in]  appTransport
+     *      Application transport handle to send packet on.  This value
+     *      is provided by the application at transport registration.
+     *
+     *  @param[in]  pktHandle
+     *      Pointer to the start of the application's transport "packet".
+     *      Could be the pointer to the start of a QMSS descriptor,
+     *      network packet, etc.
      *
      *  @retval
-     *      0 - Packet sent okay.
+     *      0   - Packet sent okay.
      *  @retval
-     *      Non-zero - Send failed.
+     *      < 0 - Packet send failed.
      */
     int32_t (*rmSendPkt)(Rm_AppTransportHandle appTransport, Rm_PacketHandle pktHandle);
 } Rm_TransportCallouts;
@@ -153,27 +196,31 @@ typedef struct {
  * @brief RM transport registration configuration structure
  */
 typedef struct {
-    /** The RM Handle for which the transport is being registered */
+    /** RM Handle for which the transport is being registered */
     Rm_Handle              rmHandle;
-    /** The Application transport handle associated with the registered
-     *  transport */
+    /** Application transport handle associated with the registered
+     *  transport.  This value can be anything that helps the application
+     *  identify the application transport "pipe" for which a RM packet
+     *  should be sent on.  For example, a QMSS queue number, network
+     *  port data structure, etc. */
     Rm_AppTransportHandle  appTransportHandle;
-    /** The transport's remote RM instance type */
+    /** Remote RM instance type at other end of the application transport 
+     *  "pipe". */
     Rm_InstType            remoteInstType;
-    /** Pointer to the transport's remote RM instance name */
+    /** Pointer to the remote RM instance name at other end of the 
+     *  application transport "pipe". */
     char                  *remoteInstName;
-    /** Used to specify whether the transport callouts are valid.
-     *  TRUE - Transport callouts are valid and will be stored by the RM
-     *         instance.
-     *  FALSE - Transport callouts are not valid and will not be stored by
+    /** Specifies whether the transport callouts are valid.
+     *  TRUE  - Transport callouts are valid and can be stored by the RM
+     *          instance.
+     *  FALSE - Transport callouts are not valid and cannot not be stored by
      *          the RM instance. */
     bool                   transportCalloutsValid;
     /** Pointers to application implemented transport APIs.  The APIs for the
      *  provided functions must match the prototypes defined in the
-     *  Rm_TransportCallouts structure.  Callouts will typically only be defined
-     *  for the first transport registered with an RM instance.  The 
-     *  transportCalloutsValid field can be used to disable RM instance's from
-     *  reading in new callout values are they're specified once. */
+     *  #Rm_TransportCallouts structure.  Callouts need only be defined
+     *  once per RM instance.  Multiple transport registrations on the same
+     *  intance need the transportsCallouts defined and set as valid once. */
     Rm_TransportCallouts   transportCallouts;   
 } Rm_TransportCfg;
 
@@ -184,26 +231,72 @@ typedef struct {
  *      receiving packets between RM instances over application transport
  *      data paths.
  *
- *  @param[in]  rmHandle
- *      RM instance to which the transport will be registered.  Used internally
- *      by RM if there are more than one RM instances per core.
+ *      RM Transport Restrictions:
+ *      a) RM Servers cannot register with other Servers
+ *      b) RM CDs cannot register with other CDs
+ *      c) RM Clients cannot register with other Clients
+ *      d) Clients cannot register with more than one CD or Server
+ *      e) Clients cannot register with both a CD and Server (either or)
+ *      f) CDs cannot register with more than one Server
  *
  *  @param[in]  transportCfg
- *      Transport registration configuration structure.  Provides information
- *      regarding the application transports remote entity.  For example,
- *      if the transCfg structure specifies the remote type is the RM Server
- *      RM will know any Server requests must be pushed to the application
- *      transport API with the transport handle returned to the application
+ *      Pointer to the transport registration configuration structure.
+ *
+ *  @param[out] result
+ *      Pointer to a signed int used to return any errors encountered during
+ *      the transport registration process.
  *
  *  @retval
- *      Success - non-NULL RM transport handle.  No two transport handles
- *                returned by RM should be the same.
+ *      Success - RM_TransportHandle and result = #RM_OK
+ *  @retval
+ *      Failure - NULL RM_TransportHandle and result = #RM_ERROR_INVALID_REMOTE_INST_TYPE
+ *  @retval
+ *      Failure - NULL RM_TransportHandle and result = #RM_ERROR_ALREADY_REGD_SERVER_OR_CD
  *  @retval
- *      Failure - NULL
+ *      Failure - NULL RM_TransportHandle and result = #RM_ERROR_NULL_CALLOUTS_WHEN_VALID 
  */
 Rm_TransportHandle Rm_transportRegister(Rm_TransportCfg *transportCfg, int32_t *result);
+
+/**
+ *  @b Description
+ *  @n  
+ *      This function unregisters the provided transportHandle from the 
+ *      RM instance
+ *
+ *  @param[in]  transportHandle
+ *      Transport handle to unregister.  The RM instance that the handle will
+ *      be unregistered from is contained within the transportHandle.
+ *
+ *  @retval
+ *      Success - #RM_OK
+ *  @retval
+ *      Failure - #RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST
+ */
 int32_t Rm_transportUnregister (Rm_TransportHandle transportHandle);
-/* Application will always free the packet */
+
+/**
+ *  @b Description
+ *  @n  
+ *      This function is called by the application when it has received a RM
+ *      packet for processing.  The application provides the transportHandle
+ *      associated with the RM instance that should receive the packet and
+ *      a pointer to the data buffer containing the Rm_Packet.
+ *
+ *      RM assumes that the application will free the data buffer containing
+ *      the Rm_Packet after RM has finished processing the packet.
+ *
+ *  @param[in]  transportHandle
+ *      RM transportHandle containing the instance that should process the
+ *      received packet.
+ *
+ *  @param[in] pkt
+ *      Pointer to the data buffer containing the Rm_Packet
+ *
+ *  @retval
+ *      Success - #RM_OK
+ *  @retval
+ *      Failure - < #RM_OK 
+ */
 int32_t Rm_receivePacket(Rm_TransportHandle transportHandle, Rm_Packet *pkt);
 
 /** 
index 7e30a2eba5522a8433bc97157c7c1b799aece496..9900a28817d0f8b74636bb103d2b0494ba588ae7 100644 (file)
--- a/src/rm.c
+++ b/src/rm.c
@@ -85,7 +85,7 @@ const char  rmVersionStr[] = RM_VERSION_STR ":" __DATE__  ":" __TIME__;
  *              will be used as the remoteOriginatingId for\r
  *              transactions that are responses to requests).\r
  */\r
-uint32_t transactionInitSequenceNum(void)\r
+static uint32_t transactionInitSequenceNum(void)\r
 {\r
     return (1);\r
 }\r
@@ -96,7 +96,7 @@ uint32_t transactionInitSequenceNum(void)
  *              specific to a RM instance.  Handles rollover of\r
  *              sequence number.\r
  */\r
-uint32_t transactionGetSequenceNum(Rm_Inst *rmInst)\r
+static uint32_t transactionGetSequenceNum(Rm_Inst *rmInst)\r
 {\r
     uint32_t sequenceNum = 0;\r
 \r
@@ -117,7 +117,7 @@ uint32_t transactionGetSequenceNum(Rm_Inst *rmInst)
  *              The allocator is also stored in the RM instance\r
  *              allocator list.            \r
  */\r
-Rm_Allocator *allocatorAdd(Rm_Inst *rmInst, const char *resourceName)\r
+static Rm_Allocator *allocatorAdd(Rm_Inst *rmInst, const char *resourceName)\r
 {\r
     Rm_Allocator *allocators   = rmInst->allocators;\r
     Rm_Allocator *newAllocator = NULL;\r
@@ -150,7 +150,7 @@ Rm_Allocator *allocatorAdd(Rm_Inst *rmInst, const char *resourceName)
  *              resource name.  The resource allocator will be\r
  *              removed from the RM instance allocator list.\r
  */\r
-int32_t allocatorDelete(Rm_Inst *rmInst, char *resourceName)\r
+static int32_t allocatorDelete(Rm_Inst *rmInst, char *resourceName)\r
 {\r
     Rm_Allocator *allocator = rmInst->allocators;\r
     Rm_Allocator *prevAllocator = NULL;\r
@@ -184,7 +184,7 @@ int32_t allocatorDelete(Rm_Inst *rmInst, char *resourceName)
  * DESCRIPTION: Adds a RM instance node to a resource node's\r
  *              list of owners.\r
  */\r
-void addOwner(Rm_ResourceNode *node, void *serviceInstNode)\r
+static void addOwner(Rm_ResourceNode *node, void *serviceInstNode)\r
 {\r
     Rm_Owner *ownerList = node->ownerList;\r
     Rm_Owner *newOwner = NULL;\r
@@ -217,7 +217,7 @@ void addOwner(Rm_ResourceNode *node, void *serviceInstNode)
  *              in the list of resource node owners.  Otherwise,\r
  *              returns FALSE.\r
  */\r
-bool isOwnedBy(Rm_ResourceNode *node, void *serviceInstNode)\r
+static bool isOwnedBy(Rm_ResourceNode *node, void *serviceInstNode)\r
 {\r
     Rm_Owner *owner = node->ownerList;\r
 \r
@@ -235,7 +235,7 @@ bool isOwnedBy(Rm_ResourceNode *node, void *serviceInstNode)
  * DESCRIPTION: Returns TRUE if the owners of two resource nodes \r
  *              are equivalent.  Otherwise, returns FALSE.\r
  */\r
-bool compareResourceNodeOwners(Rm_ResourceNode *node1, Rm_ResourceNode *node2)\r
+static bool compareResourceNodeOwners(Rm_ResourceNode *node1, Rm_ResourceNode *node2)\r
 {\r
     Rm_Owner *node1Owners = node1->ownerList;\r
     Rm_Owner *node2Owners = node2->ownerList;\r
@@ -273,7 +273,7 @@ bool compareResourceNodeOwners(Rm_ResourceNode *node1, Rm_ResourceNode *node2)
  * DESCRIPTION: Removes a RM instance node from a resource node's\r
  *              list of owners.\r
  */\r
-void deleteOwner(Rm_ResourceNode *node, void *serviceInstNode)\r
+static void deleteOwner(Rm_ResourceNode *node, void *serviceInstNode)\r
 {\r
     Rm_Owner *owner = node->ownerList;\r
     Rm_Owner *prevOwner = NULL;\r
@@ -304,7 +304,7 @@ void deleteOwner(Rm_ResourceNode *node, void *serviceInstNode)
  *              resource node that is equivalent to the the \r
  *              source resource node's owners\r
  */\r
-void copyOwners(Rm_ResourceNode *dstNode, Rm_ResourceNode *srcNode)\r
+static void copyOwners(Rm_ResourceNode *dstNode, Rm_ResourceNode *srcNode)\r
 {\r
     Rm_Owner *srcOwnerList = srcNode->ownerList;\r
     Rm_Owner *dstNewOwner;\r
@@ -333,7 +333,7 @@ void copyOwners(Rm_ResourceNode *dstNode, Rm_ResourceNode *srcNode)
  * DESCRIPTION: Deletes all owners from the owners list of a \r
  *              resource node.\r
  */\r
-void clearOwners(Rm_ResourceNode *node)\r
+static void clearOwners(Rm_ResourceNode *node)\r
 {\r
     Rm_Owner *owner = node->ownerList;\r
     Rm_Owner *nextOwner;\r
@@ -352,7 +352,7 @@ void clearOwners(Rm_ResourceNode *node)
  *              resource name and value range.  The name and value\r
  *              typically originate from the GRL.\r
  */\r
-int32_t createResourceTree(Rm_Inst *rmInst, const char *resourceName, Rm_ResourceRange *range)\r
+static int32_t createResourceTree(Rm_Inst *rmInst, const char *resourceName, Rm_ResourceRange *range)\r
 {\r
     Rm_Allocator    *allocator = NULL;\r
     Rm_ResourceTree *treeRootEntry = NULL;\r
@@ -396,8 +396,8 @@ int32_t createResourceTree(Rm_Inst *rmInst, const char *resourceName, Rm_Resourc
  *              If a valid range is found it will be returned for the \r
  *              treeAllocate algorithm to handle.\r
  */\r
-int32_t treePreAllocate(Rm_Inst *rmInst, Rm_Allocator *allocator, int32_t resourcePolicy,\r
-                        Rm_AllocatorOpInfo *opInfo)\r
+static int32_t treePreAllocate(Rm_Inst *rmInst, Rm_Allocator *allocator, int32_t resourcePolicy,\r
+                               Rm_AllocatorOpInfo *opInfo)\r
 {\r
     Rm_ResourceNode    findNode;\r
     Rm_ResourceNode   *matchingNode = NULL;\r
@@ -512,8 +512,8 @@ int32_t treePreAllocate(Rm_Inst *rmInst, Rm_Allocator *allocator, int32_t resour
  *              resource nodes that may have become equivalent (in terms\r
  *              of ownership) after the allocation.\r
  */\r
-int32_t treeAllocate(Rm_Inst *rmInst, Rm_Allocator *allocator, int32_t resourcePolicy,\r
-                     Rm_AllocatorOpInfo *opInfo)\r
+static int32_t treeAllocate(Rm_Inst *rmInst, Rm_Allocator *allocator, int32_t resourcePolicy,\r
+                            Rm_AllocatorOpInfo *opInfo)\r
 {\r
     Rm_ResourceNode     findNode;\r
     Rm_ResourceNode    *matchingNode = NULL;\r
@@ -755,7 +755,7 @@ int32_t treeAllocate(Rm_Inst *rmInst, Rm_Allocator *allocator, int32_t resourceP
  *              become equivalent (in terms of ownership) after the\r
  *              allocation.\r
  */\r
-int32_t treeFree(Rm_Allocator *allocator, Rm_AllocatorOpInfo *opInfo)\r
+static int32_t treeFree(Rm_Allocator *allocator, Rm_AllocatorOpInfo *opInfo)\r
 {\r
     Rm_ResourceNode  findNode;\r
     Rm_ResourceNode *matchingNode = NULL;\r
@@ -953,7 +953,7 @@ int32_t treeFree(Rm_Allocator *allocator, Rm_AllocatorOpInfo *opInfo)
  *              using the service callback function provided to\r
  *              the RM instance at the time of the service request.\r
  */\r
-void serviceResponder (Rm_Inst *rmInst, Rm_Transaction *transaction)\r
+static void serviceResponder (Rm_Inst *rmInst, Rm_Transaction *transaction)\r
 {\r
     Rm_ServiceRespInfo serviceResponse;\r
 \r
@@ -991,7 +991,7 @@ void serviceResponder (Rm_Inst *rmInst, Rm_Transaction *transaction)
  *              is sent via the RM transport API which is plugged\r
  *              with an application created transport path.\r
  */\r
-void transactionResponder (Rm_Inst *rmInst, Rm_Transaction *transaction)\r
+static void transactionResponder (Rm_Inst *rmInst, Rm_Transaction *transaction)\r
 {\r
     Rm_Transport    *dstTransport = NULL;\r
     Rm_PacketHandle  pktHandle = NULL;\r
@@ -1014,8 +1014,13 @@ void transactionResponder (Rm_Inst *rmInst, Rm_Transaction *transaction)
     }\r
 \r
     if (pktHandle) {\r
-        if (rmInst->transportCallouts.rmSendPkt(dstTransport->appTransportHandle, pktHandle) < RM_OK) {\r
-            transaction->state = RM_ERROR_TRANSPORT_SEND_ERROR;\r
+        if (rmInst->transportCallouts.rmSendPkt) {\r
+            if (rmInst->transportCallouts.rmSendPkt(dstTransport->appTransportHandle, pktHandle) < RM_OK) {\r
+                transaction->state = RM_ERROR_TRANSPORT_SEND_ERROR;\r
+            }\r
+        }\r
+        else {\r
+            transaction->state = RM_ERROR_TRANSPORT_SEND_NOT_REGD;\r
         }\r
     }\r
     rmTransactionQueueDelete(rmInst, transaction->localId);\r
@@ -1028,7 +1033,7 @@ void transactionResponder (Rm_Inst *rmInst, Rm_Transaction *transaction)
  *              The request is sent via the RM transport API which is\r
  *              plugged with an application created transport path.\r
  */\r
-void transactionForwarder (Rm_Inst *rmInst, Rm_Transaction *transaction)\r
+static void transactionForwarder (Rm_Inst *rmInst, Rm_Transaction *transaction)\r
 {\r
     Rm_Transport    *dstTransport = NULL;\r
     Rm_PacketHandle  pktHandle = NULL;\r
@@ -1059,9 +1064,14 @@ void transactionForwarder (Rm_Inst *rmInst, Rm_Transaction *transaction)
         }\r
 \r
         if (pktHandle) {\r
-            if (rmInst->transportCallouts.rmSendPkt(dstTransport->appTransportHandle, pktHandle) < RM_OK) {\r
-                transaction->state = RM_ERROR_TRANSPORT_SEND_ERROR;\r
+            if (rmInst->transportCallouts.rmSendPkt) {            \r
+                if (rmInst->transportCallouts.rmSendPkt(dstTransport->appTransportHandle, pktHandle) < RM_OK) {\r
+                    transaction->state = RM_ERROR_TRANSPORT_SEND_ERROR;\r
+                }\r
             }\r
+            else {\r
+                transaction->state = RM_ERROR_TRANSPORT_SEND_NOT_REGD;\r
+            }                \r
         }\r
 \r
         transaction->hasBeenForwarded = true;\r
@@ -1074,7 +1084,7 @@ void transactionForwarder (Rm_Inst *rmInst, Rm_Transaction *transaction)
  * DESCRIPTION: Issues an allocator preallocate, allocate, or free\r
  *              for an RM resource.\r
  */\r
-int32_t allocatorOperation(Rm_Inst *rmInst, Rm_AllocatorOpInfo *opInfo)\r
+static int32_t allocatorOperation(Rm_Inst *rmInst, Rm_AllocatorOpInfo *opInfo)\r
 {\r
     Rm_Allocator *allocator = NULL;\r
     int32_t       resourceOffsetInPolicy;\r
@@ -1111,8 +1121,8 @@ int32_t allocatorOperation(Rm_Inst *rmInst, Rm_AllocatorOpInfo *opInfo)
  *              retrieved from the NameServer prior to the allocation\r
  *              attempt.\r
  */\r
-void allocationHandler (Rm_Inst *rmInst, Rm_Transaction *transaction, void *validInstNode,\r
-                        uint32_t allocType)\r
+static void allocationHandler (Rm_Inst *rmInst, Rm_Transaction *transaction, void *validInstNode,\r
+                               uint32_t allocType)\r
 {\r
     Rm_AllocatorOpInfo  opInfo;\r
     Rm_NameServerObjCfg nameServerObjCfg;\r
@@ -1183,7 +1193,7 @@ void allocationHandler (Rm_Inst *rmInst, Rm_Transaction *transaction, void *vali
  *              retrieved from the NameServer prior to the free\r
  *              attempt.\r
  */\r
-void freeHandler (Rm_Inst *rmInst, Rm_Transaction *transaction, void *validInstNode)\r
+static void freeHandler (Rm_Inst *rmInst, Rm_Transaction *transaction, void *validInstNode)\r
 {\r
     Rm_AllocatorOpInfo  opInfo; \r
     Rm_NameServerObjCfg nameServerObjCfg;    \r
@@ -1242,8 +1252,8 @@ void freeHandler (Rm_Inst *rmInst, Rm_Transaction *transaction, void *validInstN
  *              values retrieved from the Linux DTB via the\r
  *              "linux-dtb-alias" properties within the GRL.\r
  */\r
-int32_t reserveLinuxResource(Rm_Inst *rmInst, Rm_LinuxAlias *linuxAlias, \r
-                             Rm_LinuxValueRange *linuxValues, Rm_AllocatorOpInfo *opInfo)\r
+static int32_t reserveLinuxResource(Rm_Inst *rmInst, Rm_LinuxAlias *linuxAlias, \r
+                                    Rm_LinuxValueRange *linuxValues, Rm_AllocatorOpInfo *opInfo)\r
 {\r
     int32_t  retVal = RM_OK;\r
     bool     baseFound = false;\r
@@ -1255,7 +1265,7 @@ int32_t reserveLinuxResource(Rm_Inst *rmInst, Rm_LinuxAlias *linuxAlias,
             opInfo->resourceInfo->base = linuxValues->value;\r
             baseFound = true;\r
 \r
-            if (linuxAlias->lengthOffset == RM_DTB_LINUX_ALIAS_OFFSET_NOT_SET) {\r
+            if (linuxAlias->lengthOffset == RM_DTB_UTIL_LINUX_ALIAS_OFFSET_NOT_SET) {\r
                 opInfo->resourceInfo->length = 1;\r
                 lengthFound = true;\r
             }\r
@@ -1286,8 +1296,8 @@ int32_t reserveLinuxResource(Rm_Inst *rmInst, Rm_LinuxAlias *linuxAlias,
  *              "linux-dtb-alias" property defined in the GRL it is \r
  *              reserved.\r
  */\r
-int32_t findAndReserveLinuxResource(Rm_Inst *rmInst, const char *resourceName, void *linuxDtb, \r
-                                    Rm_LinuxAlias *linuxAlias)\r
+static int32_t findAndReserveLinuxResource(Rm_Inst *rmInst, const char *resourceName, void *linuxDtb, \r
+                                           Rm_LinuxAlias *linuxAlias)\r
 {\r
     Rm_AllocatorOpInfo  opInfo;\r
     Rm_ResourceInfo     resourceInfo;\r
@@ -1358,7 +1368,7 @@ int32_t findAndReserveLinuxResource(Rm_Inst *rmInst, const char *resourceName, v
                         pathOffset += (strlen(linuxAlias->path + pathOffset) + 1);\r
                         linuxValueRange = rmDtbUtilLinuxExtractValues(propertyData, propertyLen);\r
                         retVal = reserveLinuxResource(rmInst, linuxAlias, \r
-                                                         linuxValueRange, &opInfo);\r
+                                                      linuxValueRange, &opInfo);\r
                         rmDtbUtilLinuxFreeValues(linuxValueRange);\r
                     }\r
                     propOffset = fdt_next_property_offset(linuxDtb, propOffset);\r
@@ -1388,8 +1398,8 @@ int32_t findAndReserveLinuxResource(Rm_Inst *rmInst, const char *resourceName, v
  *              and there are "linux-dtb-alias" properties\r
  *              specified in the GRL.\r
  */\r
-int32_t createAndInitAllocator(Rm_Inst *rmInst, const char *resourceName, \r
-                               Rm_ResourceProperties *resourceProperties, void *linuxDtb)\r
+static int32_t createAndInitAllocator(Rm_Inst *rmInst, const char *resourceName, \r
+                                      Rm_ResourceProperties *resourceProperties, void *linuxDtb)\r
 {\r
     Rm_ResourceRange    *range = NULL;\r
     Rm_ResourceRange    *rangeBasePtr = NULL;\r
@@ -1452,7 +1462,8 @@ int32_t createAndInitAllocator(Rm_Inst *rmInst, const char *resourceName,
  * DESCRIPTION: Recursively parses and stores GRL resource node \r
  *              properties using the LIBFDT APIs\r
  */\r
-int32_t parseResourceProperty(void *globalResourceDtb, int32_t offset, Rm_ResourceProperties *propertyInfo)\r
+static int32_t parseResourceProperty(void *globalResourceDtb, int32_t offset, \r
+                                     Rm_ResourceProperties *propertyInfo)\r
 {\r
        int32_t              propertyLen;\r
        const char          *propertyName;\r
@@ -1497,8 +1508,8 @@ int32_t parseResourceProperty(void *globalResourceDtb, int32_t offset, Rm_Resour
  *              resource properties to create the resource allocators.\r
  *              The LIBFDT APIs are used to parse the GRL.\r
  */\r
-int32_t parseResourceNode(Rm_Inst *rmInst, void *globalResourceDtb, int32_t nodeOffset, int32_t depth,\r
-                          void *linuxDtb)\r
+static int32_t parseResourceNode(Rm_Inst *rmInst, void *globalResourceDtb, int32_t nodeOffset, int32_t depth,\r
+                                 void *linuxDtb)\r
 {\r
        const char            *resourceName = fdt_get_name(globalResourceDtb, nodeOffset, NULL);\r
     Rm_ResourceProperties  resourceProperties;\r
@@ -1542,7 +1553,7 @@ int32_t parseResourceNode(Rm_Inst *rmInst, void *globalResourceDtb, int32_t node
  *              resource allocators using the GRL and, if\r
  *              provided, Linux DTB.\r
  */\r
-int32_t initializeAllocators(Rm_Inst *rmInst, void *globalResourceDtb, void *linuxDtb)\r
+static int32_t initializeAllocators(Rm_Inst *rmInst, void *globalResourceDtb, void *linuxDtb)\r
 {\r
     int32_t nodeOffset = RM_DTB_UTIL_STARTING_NODE_OFFSET;\r
     int32_t startDepth = RM_DTB_UTIL_STARTING_DEPTH;\r
@@ -1900,6 +1911,66 @@ void Rm_printResourceStatus(Rm_Handle rmServerHandle)
     }\r
 }\r
 \r
+/* FUNCTION PURPOSE: Display status of a RM instance\r
+ ***********************************************************************\r
+ * DESCRIPTION: Prints the current status of various RM instance\r
+ *              properties such as the state of all transactions\r
+ *              in the transaction queue and registered transports\r
+ */\r
+void Rm_printInstanceStatus(Rm_Handle rmHandle)\r
+{\r
+    Rm_Inst        *rmInst = (Rm_Inst *)rmHandle;\r
+    Rm_Transport   *transportList = (Rm_Transport *)rmInst->transports;\r
+    Rm_Transaction *transactionQ = rmInst->transactionQueue;\r
+\r
+    Rm_osalLog("Instance name: %s\n", rmInst->instName);\r
+    if (rmInst->instType == Rm_instType_SERVER) {\r
+        Rm_osalLog("Type: Server\n");\r
+    }\r
+    else if (rmInst->instType == Rm_instType_CLIENT_DELEGATE) {\r
+        Rm_osalLog("Type: Client Delegate\n");\r
+    }\r
+    else {\r
+        Rm_osalLog("Type: Client\n");\r
+    }\r
+\r
+    if (transportList) {\r
+        Rm_osalLog("\nRegistered Transports:\n");\r
+        while (transportList) {\r
+            Rm_osalLog("    Remote instName:    %s\n", transportList->remoteInstName);\r
+            if (transportList->remoteInstType == Rm_instType_SERVER) {\r
+                Rm_osalLog("    Remote instType:    Server\n");\r
+            }\r
+            else if (transportList->remoteInstType == Rm_instType_CLIENT_DELEGATE) {\r
+                Rm_osalLog("    Remote instType:    Client Delegate\n");\r
+            }\r
+            else {\r
+                Rm_osalLog("    Remote instType:    Client\n");\r
+            }\r
+            Rm_osalLog("    appTransportHandle: 0x%08x\n", transportList->appTransportHandle);\r
+            Rm_osalLog("\n");\r
+            transportList = transportList->nextTransport;\r
+        }\r
+    }\r
+\r
+    if (transactionQ) {\r
+        Rm_osalLog("\nQueued Service Transactions:\n");\r
+        while (transactionQ) {\r
+            Rm_osalLog("    Service type:       %d\n", transactionQ->type);\r
+            Rm_osalLog("    Service ID:         %d\n", transactionQ->localId);\r
+            Rm_osalLog("    Service srcInstName %s\n", transactionQ->serviceSrcInstName);\r
+            Rm_osalLog("    Service state:      %d\n", transactionQ->state);\r
+            Rm_osalLog("    Resource name:      %s\n", transactionQ->resourceInfo.name);\r
+            Rm_osalLog("    Resource base:      %d\n", transactionQ->resourceInfo.base);\r
+            Rm_osalLog("    Resource length:    %d\n", transactionQ->resourceInfo.length);\r
+            Rm_osalLog("    Resource alignment: %d\n", transactionQ->resourceInfo.alignment);\r
+            Rm_osalLog("    Resource NS name:   %s\n", transactionQ->resourceInfo.nameServerName);\r
+            Rm_osalLog("\n");\r
+            transactionQ = transactionQ->nextTransaction;\r
+        }    \r
+    }\r
+}\r
+\r
 /* FUNCTION PURPOSE: RM instance creation and initialization\r
  ***********************************************************************\r
  * DESCRIPTION: Returns a new RM instance created and initialized\r
index 3754b6d0051b2fdad70c26ee463ce1a0c5625700..9afadc32c92c98280cedff631ba15f4c6b837ad4 100644 (file)
 #include <ti/drv/rm/util/libfdt/libfdt_env.h>
 
 /**********************************************************************
- ******************** Common DTB Parsing Globals **********************
- **********************************************************************/
-
-/**********************************************************************
- *************** Global Resource List Parsing Globals *****************
+ ************ Global Resource List (GRL) Parsing Globals **************
  **********************************************************************/
 
 /* Resource List Properties - These are the property values used
  * by an application integrator to define the properties of resources
- * listed in the Device Global Resource List */
+ * listed in the Device Global Resource List (GRL) */
 const char dtbUtilResRangeProp[]        = "resource-range";
 const char dtbUtilResLinuxAliasProp[]   = "linux-dtb-alias";
 const char dtbUtilResNsAssignmentProp[] = "ns-assignment";
@@ -87,8 +83,18 @@ const char dtbUtilPolicyAllocationAlignment[] = "allocation-alignment";
  ******************* Common DTB Parsing Functions *********************
  **********************************************************************/
 
-/* Construct and return a list of ranges as specified in either the Resource
- * DTB or a Policy DTB */
+/* FUNCTION PURPOSE: Extracts ranges from a DTB
+ ***********************************************************************
+ * DESCRIPTION: Returns a list of ranges extracted from a DTB
+ *              file.  A range in the DTB is specified as <x y> where
+ *              x is a base value and y is a length value.  Ranges can
+ *              be chained in the DTB with comma separation.
+ *              Example:
+ *                  <0 10>,
+ *                  <20 100>,
+ *                  <200 100>;
+ *                  Results in a list of three ranges.
+ */
 static Rm_ResourceRange *dtbUtilCommonExtractRange(const void *dtbDataPtr, int32_t dtbDataLen)
 {
     uint32_t         *dtbRangeData = (uint32_t *)dtbDataPtr;
@@ -123,7 +129,11 @@ static Rm_ResourceRange *dtbUtilCommonExtractRange(const void *dtbDataPtr, int32
     return (startRange);
 }
 
-/* Function to clean up the memory allocated for a linked list of extracted ranges */
+/* FUNCTION PURPOSE: Deletes a range list
+ ***********************************************************************
+ * DESCRIPTION: Frees the memory associated with a list of ranges 
+ *              that were extracted from a DTB.
+ */
 static void dtbUtilCommonFreeRangeList(Rm_ResourceRange *rangeList)
 {
     Rm_ResourceRange *nextRange;
@@ -135,7 +145,18 @@ static void dtbUtilCommonFreeRangeList(Rm_ResourceRange *rangeList)
     }
 }
 
-/* Construct and return a list of values as specified in the Policy DTB */
+/* FUNCTION PURPOSE: Extracts values from a DTB
+ ***********************************************************************
+ * DESCRIPTION: Returns a list of values extracted from a DTB
+ *              file.  A value in the DTB is specified as <x> where
+ *              x is a numerical value.  Values can be chained in the 
+ *              DTB with comma separation.
+ *              Example:
+ *                  <10>,
+ *                  <20>,
+ *                  <30>;
+ *                  Results in a list of three values.
+ */
 static Rm_ResourceValue *dtbUtilCommonExtractValueList(const void *dtbDataPtr, int32_t dtbDataLen)
 {
     uint32_t         *dtbRangeData = (uint32_t *)dtbDataPtr;
@@ -167,7 +188,11 @@ static Rm_ResourceValue *dtbUtilCommonExtractValueList(const void *dtbDataPtr, i
     return (startValue);
 }
 
-/* Function to clean up the memory allocated for a linked list of extracted values */
+/* FUNCTION PURPOSE: Deletes a value list
+ ***********************************************************************
+ * DESCRIPTION: Frees the memory associated with a list of values 
+ *              that were extracted from a DTB.
+ */
 static void dtbUtilCommonFreeValueList (Rm_ResourceValue *valueList)
 {
     Rm_ResourceValue *nextValue;
@@ -183,6 +208,11 @@ static void dtbUtilCommonFreeValueList (Rm_ResourceValue *valueList)
  ************** Global Resource List Parsing Functions ****************
  **********************************************************************/
 
+/* FUNCTION PURPOSE: Returns the GRL property type
+ ***********************************************************************
+ * DESCRIPTION: Returns the GRL property type associated with the 
+ *              property name specified.
+ */
 Rm_ResourcePropType rmDtbUtilResGetPropertyType(const char * propertyName)
 {
     Rm_ResourcePropType propertyType = Rm_resourcePropType_UNKNOWN;
@@ -199,16 +229,50 @@ Rm_ResourcePropType rmDtbUtilResGetPropertyType(const char * propertyName)
     return (propertyType);
 }
 
+/* FUNCTION PURPOSE: Extracts a resource range list from a GRL DTB
+ ***********************************************************************
+ * DESCRIPTION: Returns a list of resource ranges extracted from a GRL
+ *              DTB.  A resource range in the DTB is specified as <x y> 
+ *              where x is resource base and y is a resource length
+ *              starting from x.  Resource ranges can be chained in the 
+ *              GRL DTB with comma separation.
+ *              Example:
+ *                  <0 10>,
+ *                  <10 10>,
+ *                  <20 10>;
+ *                  Results in a list of three resource ranges.
+ */
 Rm_ResourceRange *rmDtbUtilResExtractRange(const void *dtbDataPtr, int32_t dtbDataLen)
 {
     return(dtbUtilCommonExtractRange(dtbDataPtr, dtbDataLen));
 }
 
+/* FUNCTION PURPOSE: Deletes a resource range list
+ ***********************************************************************
+ * DESCRIPTION: Frees the memory associated with a list of resource 
+ *              ranges that were extracted from a GRL DTB.
+ */
 void rmDtbUtilResFreeRange(Rm_ResourceRange *rangeList)
 {
     dtbUtilCommonFreeRangeList(rangeList);
 }
 
+/* FUNCTION PURPOSE: Extracts a Linux alias list from a GRL DTB
+ ***********************************************************************
+ * DESCRIPTION: Returns a list of Linux alias paths extracted from a GRL
+ *              DTB.  A Linux alias path in the DTB is specified as a 
+ *              space separated string following by list of numerical 
+ *              values.  Each word within the space separated string 
+ *              defines a node from the Linux DTB in the path to the
+ *              Linux alias value for the resource.  The numerical values
+ *              specify the number of values at the end of the path in
+ *              the Linux DTB.  Linux alias paths can be chained in the 
+ *              GRL DTB with comma separation.
+ *              Example:
+ *                  "LinuxDtbNode1 LinuxDtbNode2 resourcehere", <1 1>,
+ *                  "LinuxDtbNode1 LinuxDtbNode2 anotherRes", <2 2 3>,
+ *                  Results in a list of two Linux alias paths.
+ */
 Rm_LinuxAlias *rmDtbUtilResExtractLinuxAlias(const void *dtbDataPtr, int32_t dtbDataLen, int32_t *result)
 {
     uint8_t       *dtbAliasData = (uint8_t *)dtbDataPtr;
@@ -261,7 +325,7 @@ Rm_LinuxAlias *rmDtbUtilResExtractLinuxAlias(const void *dtbDataPtr, int32_t dtb
                 newAlias->lengthOffset = fdt32_to_cpu(extractedValue);
             }
             else {
-                newAlias->lengthOffset = RM_DTB_LINUX_ALIAS_OFFSET_NOT_SET;
+                newAlias->lengthOffset = RM_DTB_UTIL_LINUX_ALIAS_OFFSET_NOT_SET;
             }            
             
             newAlias->nextLinuxAlias = NULL;
@@ -290,8 +354,11 @@ Rm_LinuxAlias *rmDtbUtilResExtractLinuxAlias(const void *dtbDataPtr, int32_t dtb
     return (startAlias);
 }
 
-/* Function to clean up the memory allocated for a linked list of extracted Linux
- * aliases. */
+/* FUNCTION PURPOSE: Deletes a Linux Alias list
+ ***********************************************************************
+ * DESCRIPTION: Frees the memory associated with a list of Linux 
+ *              aliases that were extracted from a GRL DTB.
+ */
 void rmDtbUtilResFreeLinuxAlias(Rm_LinuxAlias *aliasList)
 {
     Rm_LinuxAlias *nextAlias;
@@ -306,7 +373,19 @@ void rmDtbUtilResFreeLinuxAlias(Rm_LinuxAlias *aliasList)
     }
 }
 
-/* Construct and return a list of NameServer assignments as specified in the Resource DTB */
+/* FUNCTION PURPOSE: Extracts a NS assignment list from a GRL DTB
+ ***********************************************************************
+ * DESCRIPTION: Returns a list of NameServer assignments extracted from
+ *              a GRL DTB.  A NameServer assignment is specified with
+ *              a string representing the NameServer name following by
+ *              a range in <base length> format.  NameServer assignments
+ *              can be chained in the GRL DTB with comma separation.
+ *              Example:
+ *                  "Name1", <0 10>,
+ *                  "Name2", <10 10>,
+ *                  "Another Name", <20 10>;
+ *                  Results in a list of three NameServer assignments.
+ */
 Rm_NsAssignment *rmDtbUtilResExtractNsAssignment(const void *dtbDataPtr, int32_t dtbDataLen, int32_t *result)
 {
     uint8_t         *dtbNsAssignmentData = (uint8_t *)dtbDataPtr;
@@ -367,8 +446,11 @@ Rm_NsAssignment *rmDtbUtilResExtractNsAssignment(const void *dtbDataPtr, int32_t
     return (startAssignment);
 }
 
-/* Function to clean up the memory allocated for a linked list of extracted NameServer
- * assignments. */
+/* FUNCTION PURPOSE: Deletes a NameServer assignment list
+ ***********************************************************************
+ * DESCRIPTION: Frees the memory associated with a list of NameServer 
+ *              assignments that were extracted from a GRL DTB.
+ */
 void rmDtbUtilResFreeNsAssignmentList (Rm_NsAssignment *nsAssignmentList)
 {
     Rm_NsAssignment *nextAssignment;
@@ -384,6 +466,11 @@ void rmDtbUtilResFreeNsAssignmentList (Rm_NsAssignment *nsAssignmentList)
  ********************** Policy Parsing Functions **********************
  **********************************************************************/
 
+/* FUNCTION PURPOSE: Returns the Policy property type
+ ***********************************************************************
+ * DESCRIPTION: Returns the Policy property type associated with the 
+ *              property name specified.
+ */
 Rm_PolicyPropType rmDtbUtilPolicyGetPropertyType(const char * propertyName)
 {
     Rm_PolicyPropType propertyType = Rm_policyPropType_UNKNOWN;
@@ -403,6 +490,21 @@ Rm_PolicyPropType rmDtbUtilPolicyGetPropertyType(const char * propertyName)
     return (propertyType);
 }
 
+/* FUNCTION PURPOSE: Extracts a policy assignment list from a Policy DTB
+ ***********************************************************************
+ * DESCRIPTION: Returns a list of policy assignments extracted from a 
+ *              Policy DTB.  A policy assignment in the DTB is 
+ *              specified as <x y>, "permissions string" where x is 
+ *              resource base and y is a resource length starting 
+ *              from x.  "permissions string" is string specifying
+ *              which RM instances are allowed to use the resource
+ *              range.  Policy assignments can be chained in the 
+ *              Policy DTB with comma separation.
+ *              Example:
+ *                  <0 10>, "iux = (Rm_Client)",
+ *                  <10 10>, "iu = (*);
+ *                  Results in a list of two policy assignments.
+ */
 Rm_PolicyAssignment *rmDtbUtilPolicyExtractAssignments(const void *dtbDataPtr, int32_t dtbDataLen)
 {
     uint8_t             *dtbAssignmentData = (uint8_t *)dtbDataPtr;
@@ -453,6 +555,11 @@ Rm_PolicyAssignment *rmDtbUtilPolicyExtractAssignments(const void *dtbDataPtr, i
     return (startAssignment);
 }
 
+/* FUNCTION PURPOSE: Deletes a policy assignment list
+ ***********************************************************************
+ * DESCRIPTION: Frees the memory associated with a list of policy 
+ *              assignments that were extracted from a Policy DTB.
+ */
 void rmDtbUtilPolicyFreeAssignments(Rm_PolicyAssignment *assignmentList)
 {
     Rm_PolicyAssignment *nextAssignment;
@@ -467,30 +574,72 @@ void rmDtbUtilPolicyFreeAssignments(Rm_PolicyAssignment *assignmentList)
     }
 }
 
-/* Construct and return a list of allocation sizes as specified in the Policy DTB */
+/* FUNCTION PURPOSE: Extracts an allocation size from a Policy DTB
+ ***********************************************************************
+ * DESCRIPTION: Returns a list of allocation sizes extracted from a
+ *              Policy DTB.  A allocation size in the DTB is specified
+ *              as <x> where x is the allocation size for a resource.
+ *              Allocation sizes can be chained in the Policy DTB with
+ *              comma separation.
+ *              Example:
+ *                  <10>,
+ *                  <100>;
+ *                  Results in a list of two allocation sizes.
+ */
 Rm_ResourceValue *rmDtbUtilPolicyExtractAllocationSizes(const void *dtbDataPtr, int32_t dtbDataLen)
 {
     return(dtbUtilCommonExtractValueList(dtbDataPtr, dtbDataLen));
 }
 
-/* Function to clean up the memory allocated for a linked list of extracted allocation sizes */
+/* FUNCTION PURPOSE: Deletes a allocation sizes list
+ ***********************************************************************
+ * DESCRIPTION: Frees the memory associated with a list of allocation
+ *              sizes that were extracted from a Policy DTB.
+ */
 void rmDtbUtilPolicyFreeAllocationSizes (Rm_ResourceValue *allocationSizeList)
 {
     dtbUtilCommonFreeValueList(allocationSizeList);
 }
 
-/* Construct and return a list of allocation alignments as specified in the Policy DTB */
+/* FUNCTION PURPOSE: Extracts an resource alignment from a Policy DTB
+ ***********************************************************************
+ * DESCRIPTION: Returns a list of resource alignments extracted from a
+ *              Policy DTB.  A resource alignment in the DTB is specified
+ *              as <x> where x is the resource alignment for a resource.
+ *              Resource alignments can be chained in the Policy DTB with
+ *              comma separation.
+ *              Example:
+ *                  <10>,
+ *                  <100>;
+ *                  Results in a list of two resource alignments.
+ */
 Rm_ResourceValue *rmDtbUtilPolicyExtractResourceAlignments(const void *dtbDataPtr, int32_t dtbDataLen)
 {
     return(dtbUtilCommonExtractValueList(dtbDataPtr, dtbDataLen));
 }
 
-/* Function to clean up the memory allocated for a linked list of extracted allocation alignments */
+/* FUNCTION PURPOSE: Deletes a resource alignments list
+ ***********************************************************************
+ * DESCRIPTION: Frees the memory associated with a list of resource
+ *              alignments that were extracted from a Policy DTB.
+ */
 void rmDtbUtilPolicyFreeResourceAlignments (Rm_ResourceValue *alignmentList)
 {
     dtbUtilCommonFreeValueList(alignmentList);
 }
 
+/* FUNCTION PURPOSE: Extracts an valid instance list from a Policy DTB
+ ***********************************************************************
+ * DESCRIPTION: Returns a list of valid instances extracted from a
+ *              Policy DTB.  A valid instance in the DTB is specified
+ *              as "instName" where instName is the name of an RM
+ *              instance.  Valid instances can be chained in the 
+ *              Policy DTB with comma separation.
+ *              Example:
+ *                  <Rm_Client>,
+ *                  <Rm_Server>;
+ *                  Results in a list of two valid instances.
+ */
 Rm_PolicyValidInst *rmDtbUtilPolicyExtractValidInstances(const void *dtbDataPtr, int32_t dtbDataLen,
                                                          int32_t *result)
 {
@@ -534,6 +683,11 @@ Rm_PolicyValidInst *rmDtbUtilPolicyExtractValidInstances(const void *dtbDataPtr,
     return (startInst);
 }
 
+/* FUNCTION PURPOSE: Deletes a valid instnace list
+ ***********************************************************************
+ * DESCRIPTION: Frees the memory associated with a list of valid
+ *              instances that were extracted from a Policy DTB.
+ */
 void rmDtbUtilPolicyFreeValidInstances (Rm_PolicyValidInst *validInstList)
 {
     Rm_PolicyValidInst *nextInst;
@@ -549,6 +703,16 @@ void rmDtbUtilPolicyFreeValidInstances (Rm_PolicyValidInst *validInstList)
  ****************Linux DTB Parsing Defines and Functions***************
  **********************************************************************/
 
+/* FUNCTION PURPOSE: Extracts a linux value list from a Linux DTB
+ ***********************************************************************
+ * DESCRIPTION: Returns a list of values extracted from a Linux
+ *              DTB.  Linux value in the Linux DTB is specified
+ *              as <w x y z ...> where w x y z ... are a list of
+ *              numerical values.
+ *              Example:
+ *                  <1 5 10 15 20 25>;
+ *                  Results in a list of six Linux values.
+ */
 Rm_LinuxValueRange *rmDtbUtilLinuxExtractValues(const void *dtbDataPtr, int32_t dtbDataLen)
 {
     uint32_t           *dtbValueData = (uint32_t *)dtbDataPtr;
@@ -576,6 +740,11 @@ Rm_LinuxValueRange *rmDtbUtilLinuxExtractValues(const void *dtbDataPtr, int32_t
     return (startValue);
 }
 
+/* FUNCTION PURPOSE: Deletes a Linux values list
+ ***********************************************************************
+ * DESCRIPTION: Frees the memory associated with a list of Linux
+ *              values that were extracted from a Linux DTB.
+ */
 void rmDtbUtilLinuxFreeValues(Rm_LinuxValueRange *valueList)
 {
     Rm_LinuxValueRange *nextValue;
index 2129944614bc027d0e1ed4f1f732c7c4ab1d72b6..e6e765e0a9a0b9d847d009f2bcd5a660092f4552 100644 (file)
  ******************* Internal NameServer APIs *************************
  **********************************************************************/
 
+/* FUNCTION PURPOSE: Adds an object to the NameServer
+ ***********************************************************************
+ * DESCRIPTION: Adds an object mapping a name to a resource to
+ *              the NameServer tree.
+ */
 int32_t rmNameServerAddObject(Rm_NameServerObjCfg *objCfg)
 {
     Rm_NameServerNode    *newNode = NULL;
@@ -78,6 +83,12 @@ int32_t rmNameServerAddObject(Rm_NameServerObjCfg *objCfg)
     return(retVal);
 }
 
+/* FUNCTION PURPOSE: Finds a NameServer object based on the name
+ ***********************************************************************
+ * DESCRIPTION: Finds the NameServer node with the name specified
+ *              in the objCfg structure and returns the resource
+ *              values mapped to the name via the objCfg structure
+ */
 int32_t rmNameServerFindObject(Rm_NameServerObjCfg *objCfg)
 {
     Rm_NameServerNode  findNode;
@@ -98,6 +109,12 @@ int32_t rmNameServerFindObject(Rm_NameServerObjCfg *objCfg)
     return(retVal);
 }
 
+/* FUNCTION PURPOSE: Deletes an object from the NameServer
+ ***********************************************************************
+ * DESCRIPTION: Deletes the object with the name defined in the
+ *              objCfg structure from the NameServer tree.  Frees the
+ *              memory associated with the NameServer node
+ */
 int32_t rmNameServerDeleteObject(Rm_NameServerObjCfg *objCfg)
 {   
     Rm_NameServerNode  findNode;
@@ -117,6 +134,11 @@ int32_t rmNameServerDeleteObject(Rm_NameServerObjCfg *objCfg)
     return(retVal);
 }
 
+/* FUNCTION PURPOSE: Prints the NameServer objects
+ ***********************************************************************
+ * DESCRIPTION: Prints the names and the resources they're mapped
+ *              to for all objects stored in the NameServer tree.
+ */
 void rmNameServerPrintObjects(Rm_NameServerTree *nameServerTree)
 {
     Rm_NameServerNode *node;
@@ -127,6 +149,11 @@ void rmNameServerPrintObjects(Rm_NameServerTree *nameServerTree)
     }
 }
 
+/* FUNCTION PURPOSE: Initializes the NameServer tree
+ ***********************************************************************
+ * DESCRIPTION: Creates and initializes the NameServer tree
+ *              root entry.
+ */
 Rm_NameServerTree *rmNameServerInit(void)
 {
     Rm_NameServerTree *rootEntry = NULL;
index 1a4503e6542245a9915ea659601dfa6c288dbe92..356ea165986a90e69aa0fa6bb9200f937e7bd29d 100644 (file)
  *********************** Policy Globals *******************************
  **********************************************************************/
 
+/* Character used in Policies to specify all RM instances receive
+ * the defined permissions for a resource node */
 const char Rm_policyAllInstances[] = "*";
 
 /**********************************************************************
  ******************** Local Policy Functions **************************
  **********************************************************************/
 
+/* FUNCTION PURPOSE: Validates the instance names in a permissions string
+ ***********************************************************************
+ * DESCRIPTION: Returns RM_OK if all the instance names in a permissions
+ *              string match instance names defined in the valid instance
+ *              list.  RM_ERROR_PERM_STR_INST_NOT_VALID is returned if
+ *              there are any mismatches
+ */
 static int32_t policyCheckInstances(Rm_PolicyValidInstTree *validInstTree, 
                                     Rm_PolicyPermission *permissionsList)
 {
@@ -83,6 +92,14 @@ static int32_t policyCheckInstances(Rm_PolicyValidInstTree *validInstTree,
     return(RM_OK);
 }
 
+/* FUNCTION PURPOSE: Parses a permissions subgroup
+ ***********************************************************************
+ * DESCRIPTION: Returns a linked list of policy permissions defining
+ *              which RM instance referenced in the permissions subgroup
+ *              get which permissions.  Returns NULL if any syntax
+ *              errors are encountered during the parsing.  The error
+ *              is returned via the result pointer parameter.
+ */
 static Rm_PolicyPermission *policyParseSubPermission(char *permStrStart, char *permStrEnd, 
                                                      int32_t *result)
 {
@@ -382,6 +399,12 @@ static Rm_PolicyPermission *policyParseSubPermission(char *permStrStart, char *p
     return (startPerm);
 }
 
+/* FUNCTION PURPOSE: Frees a linked list of assignment permissions
+ ***********************************************************************
+ * DESCRIPTION: Frees the memory associated with a linked list of
+ *              assignment permissions extracted from a permissions
+ *              assignment subgroup in a policy DTB.
+ */
 static void policyFreeAssignmentPermissions(Rm_PolicyPermission *permissionList)
 {
     Rm_PolicyPermission *nextPerm;
@@ -393,6 +416,13 @@ static void policyFreeAssignmentPermissions(Rm_PolicyPermission *permissionList)
     }
 }
 
+/* FUNCTION PURPOSE: Extracts permissions from a Policy "assignment"
+ ***********************************************************************
+ * DESCRIPTION: Returns a linked list of permissions for a resource node
+ *              containing an "assignment" property in the Policy DTB.
+ *              Each node in the linked list will contain a valid instance
+ *              name along with the permissions assigned to the instance
+ */
 static Rm_PolicyPermission *policyGetAssignmentPermissions(Rm_PolicyAssignment *assignment, 
                                                            int32_t *result)
 {
@@ -444,6 +474,13 @@ static Rm_PolicyPermission *policyGetAssignmentPermissions(Rm_PolicyAssignment *
     return(startPerm);
 }
 
+/* FUNCTION PURPOSE: Validates a policy "assignment" string list
+ ***********************************************************************
+ * DESCRIPTION: Returns RM_OK if the specified Policy DTB "assignment"
+ *              property specification parses okay and all the RM
+ *              instances in the assignment match RM instances in the
+ *              valid instances list
+ */
 static int32_t policyValidateAssignmentPermissions(Rm_PolicyValidInstTree *root,
                                                    Rm_PolicyAssignment *assignmentList)
 {
@@ -474,6 +511,11 @@ static int32_t policyValidateAssignmentPermissions(Rm_PolicyValidInstTree *root,
  ************************ Internal Policy APIs ************************
  **********************************************************************/
 
+/* FUNCTION PURPOSE: Get a valid instace node from the valid inst tree
+ ***********************************************************************
+ * DESCRIPTION: Returns a valid instance node from the valid instance
+ *              tree that matches the specified instName
+ */
 Rm_PolicyValidInstNode *rmPolicyGetValidInstNode(Rm_PolicyValidInstTree *validInstTree, char *instName)
 {
     Rm_PolicyValidInstNode  findNode;
@@ -484,6 +526,12 @@ Rm_PolicyValidInstNode *rmPolicyGetValidInstNode(Rm_PolicyValidInstTree *validIn
     return (RB_FIND(_Rm_PolicyValidInstTree, validInstTree, &findNode));
 }
 
+/* FUNCTION PURPOSE: Gets the Linux Valid instance node
+ ***********************************************************************
+ * DESCRIPTION: Returns a pointer to the valid instance node in the
+ *              valid instance tree that matches the instance name
+ *              reserved for resource assigned to the Linux kernel.
+ */
 Rm_PolicyValidInstNode *rmPolicyGetLinuxInstNode(Rm_PolicyValidInstTree *validInstTree)
 {
     char linuxName[] = RM_ALLOCATED_TO_LINUX;
@@ -491,6 +539,12 @@ Rm_PolicyValidInstNode *rmPolicyGetLinuxInstNode(Rm_PolicyValidInstTree *validIn
     return (rmPolicyGetValidInstNode(validInstTree, linuxName));
 }
 
+/* FUNCTION PURPOSE: Validates resource permissions against a Policy DTB
+ ***********************************************************************
+ * DESCRIPTION: Returns TRUE if the instance name has the specified
+ *              permissions for the specified resource in the Policy
+ *              DTB.  Otherwise, returns FALSE.
+ */
 bool rmPolicyCheckPrivilege(Rm_PolicyCheckCfg *privilegeCfg, int32_t *result)
 {
     int32_t              propertyOffset;
@@ -579,6 +633,12 @@ bool rmPolicyCheckPrivilege(Rm_PolicyCheckCfg *privilegeCfg, int32_t *result)
     return(true);
 }
 
+/* FUNCTION PURPOSE: Returns resource base value according to the Policy
+ ***********************************************************************
+ * DESCRIPTION: Returns a resource base value based on the resource
+ *              ranges assigned to the specified valid instance by the
+ *              Policy DTB.
+ */
 uint32_t rmPolicyGetResourceBase(void *policyDtb, Rm_PolicyValidInstNode *validInstNode, 
                                  int32_t resourceOffset, uint32_t allocType, 
                                  int32_t *result)
@@ -643,6 +703,12 @@ uint32_t rmPolicyGetResourceBase(void *policyDtb, Rm_PolicyValidInstNode *validI
     return(resourceBase);
 }
 
+/* FUNCTION PURPOSE: Returns resource alignment value according to the Policy
+ ***********************************************************************
+ * DESCRIPTION: Returns a resource alignment value based on the resource
+ *              alignment assigned to the specified valid instance by the
+ *              Policy DTB.
+ */
 uint32_t rmPolicyGetResourceAlignment(void *policyDtb, int32_t resourceOffset)
 {
     int32_t            propertyOffset;
@@ -667,6 +733,13 @@ uint32_t rmPolicyGetResourceAlignment(void *policyDtb, int32_t resourceOffset)
     return(resourceAlignment);
 }
 
+/* FUNCTION PURPOSE: Get a resource's offset into a Policy
+ ***********************************************************************
+ * DESCRIPTION: Returns the location of the specified resource node
+ *              within the specified Policy in the form of an offset
+ *              into the DTB.  The resourceName and the Policy
+ *              node name must match.
+ */
 int32_t rmPolicyGetResourceOffset(void *policyDtb, char *resourceName)
 {
     int32_t     nodeOffset;
@@ -690,6 +763,13 @@ int32_t rmPolicyGetResourceOffset(void *policyDtb, char *resourceName)
     return(nodeOffset);
 }
 
+/* FUNCTION PURPOSE: Validates a Policy's resource node names
+ ***********************************************************************
+ * DESCRIPTION: Returns RM_OK if all of a Policy's resource node names
+ *              match a node name specified in the "valid-instances"
+ *              list specified at the top of the Policy.  Otherwise,
+ *              returns error
+ */
 int32_t rmPolicyValidatePolicyResourceNames(void *policyDtb, void *allocatorList)
 {
     Rm_Allocator *allocator = (Rm_Allocator *)allocatorList;
@@ -717,7 +797,16 @@ int32_t rmPolicyValidatePolicyResourceNames(void *policyDtb, void *allocatorList
     return(RM_OK);
 }
 
-/* TODO: ADD ABILITY TO RETURN THE SYNTAX ERROR LOCATION */
+/* FUNCTION PURPOSE: Validates a Policy DTB
+ ***********************************************************************
+ * DESCRIPTION: Returns RM_OK if the input Policy satisfies the
+ *              following conditions:
+ *              a) All "assignment" permission string parse okay
+ *              b) All RM instance names specified in the permission
+ *                 strings match an instance name in the valid instance
+ *                 list
+ *              c) All resource node names match a resource allocator
+ */
 int32_t rmPolicyValidatePolicy(void *policyDtb, Rm_PolicyValidInstTree *validInstTree)
 {
     int32_t              nodeOffset;
@@ -761,6 +850,14 @@ int32_t rmPolicyValidatePolicy(void *policyDtb, Rm_PolicyValidInstTree *validIns
     return(RM_OK);
 }
 
+/* FUNCTION PURPOSE: Creates the valid instance tree for a RM instance
+ ***********************************************************************
+ * DESCRIPTION: Creates the valid instance tree for a RM instance 
+ *              that has been provided a global or static policy
+ *              The valid instance tree is created from the
+ *              "valid-instances" property at the top of the Policy.
+ *              The root entry of the valid instance tree is returned.
+ */
 Rm_PolicyValidInstTree *rmPolicyCreateValidInstTree(void *policyDtb, bool addLinux, int32_t *result)
 {
     int32_t                 validInstOffset;
@@ -816,6 +913,11 @@ Rm_PolicyValidInstTree *rmPolicyCreateValidInstTree(void *policyDtb, bool addLin
     return (rootEntry);
 }
 
+/* FUNCTION PURPOSE: Deletes a valid instance tree
+ ***********************************************************************
+ * DESCRIPTION: Frees all memory associated with a Policy valid
+ *              instance tree.
+ */
 void rmPolicyFreeValidInstTree(Rm_PolicyValidInstTree *validInstTree)
 {
     Rm_PolicyValidInstNode *node;
@@ -823,7 +925,10 @@ void rmPolicyFreeValidInstTree(Rm_PolicyValidInstTree *validInstTree)
     RB_FOREACH(node, _Rm_PolicyValidInstTree, validInstTree) {               
         RB_REMOVE(_Rm_PolicyValidInstTree, validInstTree, node);
         rmPolicyValidInstNodeFree(node);
-    }        
-    Rm_osalFree((void *)validInstTree, sizeof(Rm_PolicyValidInstTree));
+    }
+    if (RB_MIN(_Rm_PolicyValidInstTree, validInstTree) == NULL) {
+        /* No more valid instance nodes in tree */
+        Rm_osalFree((void *)validInstTree, sizeof(Rm_PolicyValidInstTree));
+    }
 }
 
index a438a39e05864466627fb672aa2c0da75d74b968..e06bd20f2d7ae482c088f1eed20bf006a82cbcbf 100644 (file)
@@ -1,5 +1,5 @@
 /**
- *   @file  rmservices.c
+ *   @file  rm_services.c
  *
  *   @brief   
  *      This is the Resource Manager services source.
index a68288ea962a1c5807ece042a7abae4300c2ee94..af6746c5a87af48f4afab2e3f4f24272563aa0f0 100644 (file)
@@ -1,8 +1,8 @@
 /**\r
- *   @file  rm.c\r
+ *   @file  rm_transport.c\r
  *\r
  *   @brief   \r
- *      This is the Resource Manager source.\r
+ *      This is the Resource Manager transport source.\r
  *\r
  *  \par\r
  *  ============================================================================\r
 #include <rm_osal.h>\r
 \r
 /**********************************************************************\r
- ********************** Internal Functions ****************************\r
+ ************************ Local Functions *****************************\r
  **********************************************************************/\r
 \r
+/* FUNCTION PURPOSE: Adds a transport\r
+ ***********************************************************************\r
+ * DESCRIPTION: Returns a pointer to a transport structure that\r
+ *              was created, initialized, and added to the \r
+ *              instance transport list.\r
+ */\r
 static Rm_Transport *transportAdd(Rm_TransportCfg *transportCfg)\r
 {\r
     Rm_Inst      *rmInst = (Rm_Inst *) transportCfg->rmHandle;\r
@@ -87,7 +93,12 @@ static Rm_Transport *transportAdd(Rm_TransportCfg *transportCfg)
     return (newTransport);\r
 }\r
 \r
-static bool transportIsTransportRegistered(Rm_Handle rmHandle, Rm_Transport *transport)\r
+/* FUNCTION PURPOSE: Tests if a transport is registered to an instance\r
+ ***********************************************************************\r
+ * DESCRIPTION: Returns TRUE if the supplied transport is found in\r
+ *              the instance transport list.  Otherwise, returns FALSE\r
+ */\r
+static bool transportIsRegistered(Rm_Handle rmHandle, Rm_Transport *transport)\r
 {\r
     Rm_Inst      *rmInst = (Rm_Inst *)rmHandle;\r
     Rm_Transport *transportList = (Rm_Transport *)rmInst->transports;\r
@@ -101,6 +112,12 @@ static bool transportIsTransportRegistered(Rm_Handle rmHandle, Rm_Transport *tra
     return (false);\r
 }\r
 \r
+/* FUNCTION PURPOSE: Deletes a transport\r
+ ***********************************************************************\r
+ * DESCRIPTION: Removes a transport from an instance transport list\r
+ *              and then frees the memory associated with the transport\r
+ *              data structure\r
+ */\r
 static void transportDelete(Rm_Transport *transport)\r
 {\r
     Rm_Inst      *rmInst = (Rm_Inst *)transport->rmHandle;\r
@@ -125,6 +142,17 @@ static void transportDelete(Rm_Transport *transport)
     Rm_osalFree((void *)transport, sizeof(Rm_Transport));\r
 }\r
 \r
+/**********************************************************************\r
+ ********************** Internal Functions ****************************\r
+ **********************************************************************/\r
+\r
+/* FUNCTION PURPOSE: Finds a transport based on remote inst name\r
+ ***********************************************************************\r
+ * DESCRIPTION: Returns a pointer to the transport within an instance's\r
+ *              transport list that matches the provided remote\r
+ *              instance name.  NULL is returned if no transports in \r
+ *              the list match the remote instance name.\r
+ */\r
 Rm_Transport *rmTransportFindRemoteName(Rm_Transport *transports, char *remoteName)\r
 {\r
     while (transports) {\r
@@ -136,6 +164,13 @@ Rm_Transport *rmTransportFindRemoteName(Rm_Transport *transports, char *remoteNa
     return (transports);\r
 }\r
 \r
+/* FUNCTION PURPOSE: Finds a transport based on remote inst type\r
+ ***********************************************************************\r
+ * DESCRIPTION: Returns a pointer to the transport within an instance's\r
+ *              transport list that matches the provided remote\r
+ *              instance type.  NULL is returned if no transports in \r
+ *              the list match the remote instance type.\r
+ */\r
 Rm_Transport *rmTransportFindRemoteInstType(Rm_Transport *transports, Rm_InstType remoteInstType)\r
 {\r
     while (transports) {\r
@@ -147,6 +182,14 @@ Rm_Transport *rmTransportFindRemoteInstType(Rm_Transport *transports, Rm_InstTyp
     return (transports);\r
 }\r
 \r
+/* FUNCTION PURPOSE: Creates a resource request packet\r
+ ***********************************************************************\r
+ * DESCRIPTION: Returns a RM packet handle that points to a RM\r
+ *              resource request packet that has been prepared\r
+ *              for sending to another RM instance.  The packet\r
+ *              is allocated via the rmAllocPkt API using the\r
+ *              appTransport handle provided by the application\r
+ */\r
 Rm_PacketHandle rmTransportCreateResourceReqPkt(Rm_Inst *rmInst, Rm_AppTransportHandle appTransport,\r
                                                 Rm_Transaction *transaction)\r
 {\r
@@ -154,36 +197,49 @@ Rm_PacketHandle rmTransportCreateResourceReqPkt(Rm_Inst *rmInst, Rm_AppTransport
     Rm_PacketHandle        pktHandle = NULL;\r
     Rm_ResourceRequestPkt *resourceReqPkt = NULL;\r
 \r
-    if ((rmPkt = rmInst->transportCallouts.rmAllocPkt(appTransport, \r
-                                                      sizeof(Rm_Packet),\r
-                                                      &pktHandle)) == NULL) {\r
-        transaction->state = RM_ERROR_TRANSPORT_ALLOC_PKT_ERROR;\r
-        return (NULL);\r
-    }\r
-   \r
-    rmPkt->pktType = Rm_pktType_RESOURCE_REQUEST;\r
-    resourceReqPkt = (Rm_ResourceRequestPkt *) rmPkt->data;\r
-    resourceReqPkt->requestId = transaction->localId;\r
-    if (transaction->type == Rm_service_RESOURCE_ALLOCATE_INIT) {\r
-        resourceReqPkt->resourceReqType = Rm_resReqPktType_ALLOCATE_INIT;\r
-    }\r
-    else if (transaction->type == Rm_service_RESOURCE_ALLOCATE_USE) {\r
-        resourceReqPkt->resourceReqType = Rm_resReqPktType_ALLOCATE_USE;\r
-    }    \r
-    else if (transaction->type == Rm_service_RESOURCE_FREE) {\r
-        resourceReqPkt->resourceReqType = Rm_resReqPktType_FREE;\r
-    }\r
-    else if (transaction->type == Rm_service_RESOURCE_GET_BY_NAME) {\r
-        resourceReqPkt->resourceReqType = Rm_resReqPktType_GET_NAMED;\r
+    if (rmInst->transportCallouts.rmAllocPkt) {\r
+        if ((rmPkt = rmInst->transportCallouts.rmAllocPkt(appTransport, \r
+                                                          sizeof(Rm_Packet),\r
+                                                          &pktHandle)) == NULL) {\r
+            transaction->state = RM_ERROR_TRANSPORT_ALLOC_PKT_ERROR;\r
+            return (NULL);\r
+        }\r
+       \r
+        rmPkt->pktType = Rm_pktType_RESOURCE_REQUEST;\r
+        resourceReqPkt = (Rm_ResourceRequestPkt *) rmPkt->data;\r
+        resourceReqPkt->requestId = transaction->localId;\r
+        if (transaction->type == Rm_service_RESOURCE_ALLOCATE_INIT) {\r
+            resourceReqPkt->resourceReqType = Rm_resReqPktType_ALLOCATE_INIT;\r
+        }\r
+        else if (transaction->type == Rm_service_RESOURCE_ALLOCATE_USE) {\r
+            resourceReqPkt->resourceReqType = Rm_resReqPktType_ALLOCATE_USE;\r
+        }    \r
+        else if (transaction->type == Rm_service_RESOURCE_FREE) {\r
+            resourceReqPkt->resourceReqType = Rm_resReqPktType_FREE;\r
+        }\r
+        else if (transaction->type == Rm_service_RESOURCE_GET_BY_NAME) {\r
+            resourceReqPkt->resourceReqType = Rm_resReqPktType_GET_NAMED;\r
+        }\r
+        strncpy(resourceReqPkt->pktSrcInstName, rmInst->instName, RM_NAME_MAX_CHARS);\r
+        strncpy(resourceReqPkt->serviceSrcInstName, transaction->serviceSrcInstName, RM_NAME_MAX_CHARS);\r
+        memcpy ((void *)&(resourceReqPkt->resourceInfo), (void *)&(transaction->resourceInfo),\r
+                sizeof(Rm_ResourceInfo));\r
     }\r
-    strncpy(resourceReqPkt->pktSrcInstName, rmInst->instName, RM_NAME_MAX_CHARS);\r
-    strncpy(resourceReqPkt->serviceSrcInstName, transaction->serviceSrcInstName, RM_NAME_MAX_CHARS);\r
-    memcpy ((void *)&(resourceReqPkt->resourceInfo), (void *)&(transaction->resourceInfo),\r
-            sizeof(Rm_ResourceInfo));\r
+    else {\r
+        transaction->state = RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD;\r
+    }        \r
     \r
     return (pktHandle);\r
 }\r
 \r
+/* FUNCTION PURPOSE: Creates a resource response packet\r
+ ***********************************************************************\r
+ * DESCRIPTION: Returns a RM packet handle that points to a RM\r
+ *              resource response packet that has been prepared\r
+ *              for sending to another RM instance.  The packet\r
+ *              is allocated via the rmAllocPkt API using the\r
+ *              appTransport handle provided by the application\r
+ */\r
 Rm_PacketHandle rmTransportCreateResourceResponsePkt(Rm_Inst *rmInst, Rm_AppTransportHandle appTransport,\r
                                                      Rm_Transaction *transaction)\r
 {\r
@@ -191,23 +247,36 @@ Rm_PacketHandle rmTransportCreateResourceResponsePkt(Rm_Inst *rmInst, Rm_AppTran
     Rm_PacketHandle         pktHandle = NULL;\r
     Rm_ResourceResponsePkt *resourceRespPkt = NULL;\r
 \r
-    if ((rmPkt = rmInst->transportCallouts.rmAllocPkt(appTransport, \r
-                                                      sizeof(Rm_Packet),\r
-                                                      &pktHandle)) == NULL) {\r
-        transaction->state = RM_ERROR_TRANSPORT_ALLOC_PKT_ERROR;\r
-        return (NULL);\r
+    if (rmInst->transportCallouts.rmAllocPkt) {\r
+        if ((rmPkt = rmInst->transportCallouts.rmAllocPkt(appTransport, \r
+                                                          sizeof(Rm_Packet),\r
+                                                          &pktHandle)) == NULL) {\r
+            transaction->state = RM_ERROR_TRANSPORT_ALLOC_PKT_ERROR;\r
+            return (NULL);\r
+        }\r
+     \r
+        rmPkt->pktType = Rm_pktType_RESOURCE_RESPONSE;                 \r
+        resourceRespPkt = (Rm_ResourceResponsePkt *)rmPkt->data;\r
+        resourceRespPkt->responseId = transaction->remoteOriginatingId;\r
+        resourceRespPkt->requestState = transaction->state;\r
+        memcpy ((void *)&(resourceRespPkt->resourceInfo), (void *)&(transaction->resourceInfo),\r
+                sizeof(Rm_ResourceInfo));\r
     }\r
\r
-    rmPkt->pktType = Rm_pktType_RESOURCE_RESPONSE;                 \r
-    resourceRespPkt = (Rm_ResourceResponsePkt *)rmPkt->data;\r
-    resourceRespPkt->responseId = transaction->remoteOriginatingId;\r
-    resourceRespPkt->requestState = transaction->state;\r
-    memcpy ((void *)&(resourceRespPkt->resourceInfo), (void *)&(transaction->resourceInfo),\r
-            sizeof(Rm_ResourceInfo));\r
+    else {\r
+        transaction->state = RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD;\r
+    }        \r
 \r
     return (pktHandle);\r
 }\r
 \r
+/* FUNCTION PURPOSE: Creates a NameServer request packet\r
+ ***********************************************************************\r
+ * DESCRIPTION: Returns a RM packet handle that points to a RM\r
+ *              NameServer request packet that has been prepared\r
+ *              for sending to another RM instance.  The packet\r
+ *              is allocated via the rmAllocPkt API using the\r
+ *              appTransport handle provided by the application\r
+ */\r
 Rm_PacketHandle rmTransportCreateNsRequestPkt(Rm_Inst *rmInst, Rm_AppTransportHandle appTransport,\r
                                               Rm_Transaction *transaction)\r
 {\r
@@ -215,30 +284,43 @@ Rm_PacketHandle rmTransportCreateNsRequestPkt(Rm_Inst *rmInst, Rm_AppTransportHa
     Rm_PacketHandle  pktHandle = NULL;    \r
     Rm_NsRequestPkt *nsReqPkt = NULL;\r
 \r
-    if ((rmPkt = rmInst->transportCallouts.rmAllocPkt(appTransport, \r
-                                                      sizeof(Rm_Packet),\r
-                                                      &pktHandle)) == NULL) {\r
-        transaction->state = RM_ERROR_TRANSPORT_ALLOC_PKT_ERROR;\r
-        return (NULL);\r
-    }\r
+    if (rmInst->transportCallouts.rmAllocPkt) {\r
+        if ((rmPkt = rmInst->transportCallouts.rmAllocPkt(appTransport, \r
+                                                          sizeof(Rm_Packet),\r
+                                                          &pktHandle)) == NULL) {\r
+            transaction->state = RM_ERROR_TRANSPORT_ALLOC_PKT_ERROR;\r
+            return (NULL);\r
+        }\r
 \r
-    rmPkt->pktType = Rm_pktType_NAMESERVER_REQUEST;                   \r
-    nsReqPkt = (Rm_NsRequestPkt *)rmPkt->data;\r
-    nsReqPkt->requestId = transaction->localId;\r
-    if (transaction->type == Rm_service_RESOURCE_MAP_TO_NAME) {\r
-        nsReqPkt->nsRequestType = Rm_nsReqPktType_MAP_RESOURCE;\r
-    }\r
-    else if (transaction->type == Rm_service_RESOURCE_UNMAP_NAME) {\r
-        nsReqPkt->nsRequestType = Rm_nsReqPktType_UNMAP_RESOURCE;\r
+        rmPkt->pktType = Rm_pktType_NAMESERVER_REQUEST;                   \r
+        nsReqPkt = (Rm_NsRequestPkt *)rmPkt->data;\r
+        nsReqPkt->requestId = transaction->localId;\r
+        if (transaction->type == Rm_service_RESOURCE_MAP_TO_NAME) {\r
+            nsReqPkt->nsRequestType = Rm_nsReqPktType_MAP_RESOURCE;\r
+        }\r
+        else if (transaction->type == Rm_service_RESOURCE_UNMAP_NAME) {\r
+            nsReqPkt->nsRequestType = Rm_nsReqPktType_UNMAP_RESOURCE;\r
+        }\r
+        strncpy(nsReqPkt->pktSrcInstName, rmInst->instName, RM_NAME_MAX_CHARS);\r
+        strncpy(nsReqPkt->serviceSrcInstName, transaction->serviceSrcInstName, RM_NAME_MAX_CHARS);\r
+        memcpy ((void *)&(nsReqPkt->resourceInfo), (void *)&(transaction->resourceInfo),\r
+                sizeof(Rm_ResourceInfo));\r
     }\r
-    strncpy(nsReqPkt->pktSrcInstName, rmInst->instName, RM_NAME_MAX_CHARS);\r
-    strncpy(nsReqPkt->serviceSrcInstName, transaction->serviceSrcInstName, RM_NAME_MAX_CHARS);\r
-    memcpy ((void *)&(nsReqPkt->resourceInfo), (void *)&(transaction->resourceInfo),\r
-            sizeof(Rm_ResourceInfo));\r
+    else {\r
+        transaction->state = RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD;\r
+    }        \r
     \r
     return (pktHandle);\r
 }\r
 \r
+/* FUNCTION PURPOSE: Creates a NameServer response packet\r
+ ***********************************************************************\r
+ * DESCRIPTION: Returns a RM packet handle that points to a RM\r
+ *              NameServer response packet that has been prepared\r
+ *              for sending to another RM instance.  The packet\r
+ *              is allocated via the rmAllocPkt API using the\r
+ *              appTransport handle provided by the application\r
+ */\r
 Rm_PacketHandle rmTransportCreateNsResponsePkt(Rm_Inst *rmInst, Rm_AppTransportHandle appTransport,\r
                                                Rm_Transaction *transaction)\r
 {\r
@@ -246,17 +328,22 @@ Rm_PacketHandle rmTransportCreateNsResponsePkt(Rm_Inst *rmInst, Rm_AppTransportH
     Rm_PacketHandle   pktHandle = NULL;\r
     Rm_NsResponsePkt *nsRespPkt = NULL;\r
 \r
-    if ((rmPkt = rmInst->transportCallouts.rmAllocPkt(appTransport, \r
-                                                      sizeof(Rm_Packet),\r
-                                                      &pktHandle)) == NULL) {\r
-        transaction->state = RM_ERROR_TRANSPORT_ALLOC_PKT_ERROR;\r
-        return (NULL);\r
+    if (rmInst->transportCallouts.rmAllocPkt) {\r
+        if ((rmPkt = rmInst->transportCallouts.rmAllocPkt(appTransport, \r
+                                                          sizeof(Rm_Packet),\r
+                                                          &pktHandle)) == NULL) {\r
+            transaction->state = RM_ERROR_TRANSPORT_ALLOC_PKT_ERROR;\r
+            return (NULL);\r
+        }\r
+     \r
+        rmPkt->pktType = Rm_pktType_NAMESERVER_RESPONSE;                \r
+        nsRespPkt = (Rm_NsResponsePkt *)rmPkt->data;\r
+        nsRespPkt->responseId = transaction->remoteOriginatingId;\r
+        nsRespPkt->requestState = transaction->state;\r
+    }\r
+    else {\r
+        transaction->state = RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD;\r
     }\r
\r
-    rmPkt->pktType = Rm_pktType_NAMESERVER_RESPONSE;                \r
-    nsRespPkt = (Rm_NsResponsePkt *)rmPkt->data;\r
-    nsRespPkt->responseId = transaction->remoteOriginatingId;\r
-    nsRespPkt->requestState = transaction->state;\r
 \r
     return (pktHandle);\r
 }\r
@@ -265,6 +352,18 @@ Rm_PacketHandle rmTransportCreateNsResponsePkt(Rm_Inst *rmInst, Rm_AppTransportH
  ********************* Application visible APIs ***********************\r
  **********************************************************************/\r
 \r
+/* FUNCTION PURPOSE: Registers an app transport with a RM instance\r
+ ***********************************************************************\r
+ * DESCRIPTION: Returns a transport handle to the application that\r
+ *              has been registered with an RM instance.  The handle\r
+ *              is used by the application to route packets to the\r
+ *              proper RM instance's based on the application\r
+ *              transport receive code.  The handle is also used\r
+ *              internally by RM to route request and response \r
+ *              packets to the correct application transports. NULL\r
+ *              is returned for the transport handle if any errors\r
+ *              are encountered.\r
+ */\r
 Rm_TransportHandle Rm_transportRegister (Rm_TransportCfg *transportCfg, int32_t *result)\r
 {\r
     Rm_Inst      *rmInst = (Rm_Inst *) transportCfg->rmHandle;\r
@@ -316,13 +415,19 @@ Rm_TransportHandle Rm_transportRegister (Rm_TransportCfg *transportCfg, int32_t
     return ((Rm_TransportHandle) transport);\r
 }\r
 \r
+/* FUNCTION PURPOSE: Unregisters an app transport from a RM instance\r
+ ***********************************************************************\r
+ * DESCRIPTION: Deletes a registered transport from the transport\r
+ *              list and cleans up the memory associated with the\r
+ *              transport data structure.\r
+ */\r
 int32_t Rm_transportUnregister(Rm_TransportHandle transportHandle)\r
 {\r
     Rm_Transport *transport = (Rm_Transport *)transportHandle;\r
     Rm_Inst      *rmInst = (Rm_Inst *)transport->rmHandle;\r
     int32_t       retVal = RM_OK;  \r
 \r
-    if (transportIsTransportRegistered(transport->rmHandle, transport)) {\r
+    if (transportIsRegistered(transport->rmHandle, transport)) {\r
         if ((transport->remoteInstType == Rm_instType_CLIENT_DELEGATE) ||\r
             (transport->remoteInstType == Rm_instType_SERVER)) {\r
             rmInst->registeredWithDelegateOrServer = false;\r
@@ -335,15 +440,18 @@ int32_t Rm_transportUnregister(Rm_TransportHandle transportHandle)
     return (retVal);\r
 }\r
 \r
-/* Used by the application to pass RM packets received from a transport to RM.\r
- * Function can be called from polling or ISR context. */\r
+/* FUNCTION PURPOSE: Receives RM packets\r
+ ***********************************************************************\r
+ * DESCRIPTION: The application provides RM packets received on the\r
+ *              application transports to RM via this API.  Function\r
+ *              can be called from polling or ISR contexts. */\r
 int32_t Rm_receivePacket(Rm_TransportHandle transportHandle, Rm_Packet *pkt)\r
 {\r\r\r
     Rm_Transport   *transport = (Rm_Transport *)transportHandle;\r
     Rm_Inst        *rmInst = (Rm_Inst *)transport->rmHandle;\r
     Rm_Transaction *transaction;\r
 \r
-    if (!transportIsTransportRegistered(transport->rmHandle, transport)) {\r
+    if (!transportIsRegistered(transport->rmHandle, transport)) {\r
         return (RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST);\r
     }\r
 \r
index 7f2d78d866ceb57be2ad0d9bb0e3fcdd6ac615bc..f14dee50b7aa78c14edd7892d2ec745f28bbc686 100644 (file)
  ********************* NameServer Tree Functions **********************
  **********************************************************************/
 
+/* FUNCTION PURPOSE: Creates a new NameServer tree node
+ ***********************************************************************
+ * DESCRIPTION: Creates a new NameServer tree node with the
+ *              specified name and the resource values it is
+ *              tied to.
+ */
 Rm_NameServerNode *rmNameServerNodeNew(Rm_NameServerNodeCfg *nodeCfg)
 {
     Rm_NameServerNode *newNode = NULL;
@@ -71,6 +77,10 @@ Rm_NameServerNode *rmNameServerNodeNew(Rm_NameServerNodeCfg *nodeCfg)
     return(newNode);
 }
 
+/* FUNCTION PURPOSE: Deletes a NameServer tree node
+ ***********************************************************************
+ * DESCRIPTION: Deletes the specified NameServer tree node.
+ */
 void rmNameServerNodeFree(Rm_NameServerNode *node)
 {
     if (node) {
@@ -78,13 +88,17 @@ void rmNameServerNodeFree(Rm_NameServerNode *node)
     }
 }
 
-/* Prototype for NameServer node comparison function
- * node1 < node2 --> return < 0
- * node1 = node2 --> return 0
- * node1 > node2 --> return > 0 */
+/* FUNCTION PURPOSE: Compares two NameServer tree nodes
+ ***********************************************************************
+ * DESCRIPTION: Returns the result of a comparison of two 
+ *              NameServer tree node names.
+ *              node1 name < node2 name --> return < 0
+ *              node1 name = node2 name --> return 0
+ *              node1 name > node2 name --> return > 0
+ */
 int rmNameServerNodeCompare(Rm_NameServerNode *node1, Rm_NameServerNode *node2)
 {
-    return(strcmp(node1->objName, node2->objName));
+    return(strncmp(node1->objName, node2->objName, RM_NAME_MAX_CHARS));
 }
 
 /* Generate the NameServer tree manipulation functions */
@@ -93,6 +107,12 @@ RB_GENERATE(_Rm_NameServerTree, _Rm_NameServerNode, linkage, rmNameServerNodeCom
 /**********************************************************************
  *************** Policy Valid Instance Tree Functions *****************
  **********************************************************************/
+
+/* FUNCTION PURPOSE: Creates a new valid instance tree node
+ ***********************************************************************
+ * DESCRIPTION: Creates a new valid instance tree node with the
+ *              specified name.
+ */
 Rm_PolicyValidInstNode *rmPolicyValidInstNodeNew(char *instName)
 {
     Rm_PolicyValidInstNode *newNode = NULL;
@@ -106,6 +126,11 @@ Rm_PolicyValidInstNode *rmPolicyValidInstNodeNew(char *instName)
     return(newNode);
 }
 
+/* FUNCTION PURPOSE: Deletes a valid instance tree node
+ ***********************************************************************
+ * DESCRIPTION: Deletes the specified valind instance tree node
+ *              if it has zero allocation references.
+ */
 void rmPolicyValidInstNodeFree(Rm_PolicyValidInstNode *node)
 {
     if (node->allocRefCount == 0) {
@@ -113,9 +138,17 @@ void rmPolicyValidInstNodeFree(Rm_PolicyValidInstNode *node)
     }
 }
 
+/* FUNCTION PURPOSE: Compares two valid instance tree nodes
+ ***********************************************************************
+ * DESCRIPTION: Returns the result of a comparison of two 
+ *              valid instance tree node names.
+ *              node1 name < node2 name --> return < 0
+ *              node1 name = node2 name --> return 0
+ *              node1 name > node2 name --> return > 0
+ */
 int rmPolicyValidInstNodeCompare(Rm_PolicyValidInstNode *node1, Rm_PolicyValidInstNode *node2)
 {
-    return(strcmp(node1->name, node2->name));
+    return(strncmp(node1->name, node2->name, RM_NAME_MAX_CHARS));
 }
 
 /* Generate the valid instance tree manipulation functions */
@@ -125,6 +158,11 @@ RB_GENERATE(_Rm_PolicyValidInstTree, _Rm_PolicyValidInstNode, linkage, rmPolicyV
  ***************** Allocator Resource Tree Functions ******************
  **********************************************************************/
 
+/* FUNCTION PURPOSE: Creates a new resource tree node
+ ***********************************************************************
+ * DESCRIPTION: Creates a new resource tree node with the
+ *              specified name resource values.
+ */
 Rm_ResourceNode *rmResourceNodeNew(uint32_t resourceBase, uint32_t resourceLength)
 {
     Rm_ResourceNode *newNode = NULL;
@@ -140,6 +178,11 @@ Rm_ResourceNode *rmResourceNodeNew(uint32_t resourceBase, uint32_t resourceLengt
     return(newNode);
 }
 
+/* FUNCTION PURPOSE: Deletes a resource tree node
+ ***********************************************************************
+ * DESCRIPTION: Deletes the specified resource tree node
+ *              if its allocation count is zero.
+ */
 void rmResourceNodeFree(Rm_ResourceNode *node)
 {
     if (node->allocationCount == 0) {
@@ -147,6 +190,15 @@ void rmResourceNodeFree(Rm_ResourceNode *node)
     }
 }
 
+/* FUNCTION PURPOSE: Compares two resource tree nodes
+ ***********************************************************************
+ * DESCRIPTION: Returns the result of a comparison of two 
+ *              resource tree node value ranges.
+ *              |node1 range||node2 range| --> return < 0
+ *                 |node1 range|
+ *                   |node2 range| --> return 0 (any overlap in ranges)
+ *              |node2 range||node1 range| --> return > 0
+ */
 int rmResourceNodeCompare(Rm_ResourceNode *node1, Rm_ResourceNode *node2)
 {
     uint32_t node1End = node1->base + node1->length - 1;
@@ -168,6 +220,6 @@ int rmResourceNodeCompare(Rm_ResourceNode *node1, Rm_ResourceNode *node2)
     }
 }
 
-/* Generate the red-black tree manipulation functions */
+/* Generate the resource tree manipulation functions */
 RB_GENERATE(_Rm_AllocatorResourceTree, _Rm_ResourceNode, linkage, rmResourceNodeCompare)
 
index 54b13604e5d117a56a94dd0bc8bc312dd8ab0b6a..3f77372d346b683c105cce1a58d7008176efce91 100644 (file)
@@ -2,7 +2,7 @@
  *   @file  rm_osal.c
  *
  *   @brief
- *      This is the OS abstraction layer and is used by the the RM LLD.
+ *      This is the OS abstraction layer used by the Resource Manager.
  *
  *  \par
  *  ============================================================================
@@ -59,16 +59,10 @@ uint32_t rmFreeCounter   = 0;
  *************************** OSAL Functions **************************
  **********************************************************************/
 
-/**
- *  @b Description
- *  @n
- *      The function is used to allocate a memory block of the specified size.
- *
- *  @param[in]  num_bytes
- *      Number of bytes to be allocated.
- *
- *  @retval
- *      Allocated block address
+/* FUNCTION PURPOSE: Allocates memory
+ ***********************************************************************
+ * DESCRIPTION: The function is used to allocate a memory block of the
+ *              specified size.
  */
 void* Osal_rmMalloc (uint32_t num_bytes)
 {
@@ -81,20 +75,11 @@ void* Osal_rmMalloc (uint32_t num_bytes)
        return Memory_alloc(NULL, num_bytes, 0, &errorBlock);
 }
 
-/**
- *  @b Description
- *  @n
- *      The function is used to free a memory block of the specified size.
- *
- *  @param[in]  ptr
- *      Pointer to the memory block to be cleaned up.
- *
- *  @param[in]  size
- *      Size of the memory block to be cleaned up.
- *
- *  @retval
- *      Not Applicable
- */
+/* FUNCTION PURPOSE: Frees memory
+ ***********************************************************************
+ * DESCRIPTION: The function is used to free a memory block of the
+ *              specified size.
+ */ 
 void Osal_rmFree (void *ptr, uint32_t size)
 {
     /* Increment the free counter. */
@@ -102,6 +87,10 @@ void Osal_rmFree (void *ptr, uint32_t size)
        Memory_free(NULL, ptr, size);
 }
 
+/* FUNCTION PURPOSE: Prints a variable list
+ ***********************************************************************
+ * DESCRIPTION: The function is used to print a string to the console
+ */
 void Osal_rmLog (char *fmt, ... )
 {
     VaList ap;
index f2c0ab6ea0f1f4c14fdf257eb30f9ad822594c34..e0b4a641751846311795404d38945f1c6b6f4b3a 100644 (file)
@@ -464,6 +464,15 @@ void testRmTsk(UArg arg0, UArg arg1)
      * RM instances */
     if (MultiProc_self() == 0) {
         rmServerServiceHandle = Rm_serviceOpenHandle(rmServerHandle, &result);
+
+        Rm_printInstanceStatus(rmServerHandle);
+    }
+    else if (MultiProc_self() == 1) {
+        /* CD and Client serviceHandles were allocated in main() for static allocations.
+         * just reuse */
+         
+        Rm_printInstanceStatus(rmClientDelegateHandle);
+        Rm_printInstanceStatus(rmClientHandle);
     }
 
     memset((void *)&requestInfo, 0, sizeof(Rm_ServiceReqInfo));
@@ -689,8 +698,6 @@ void testRmTsk(UArg arg0, UArg arg1)
                                                                                 responseInfo.serviceState);
         }            
         
-        Rm_printResourceStatus(rmServerHandle);   
-        
         memset((void *) &requestInfo, 0, sizeof(Rm_ServiceReqInfo));        
         requestInfo.type = Rm_service_RESOURCE_FREE;
         requestInfo.resourceName = resourceNameAifRxCh;
@@ -713,9 +720,7 @@ void testRmTsk(UArg arg0, UArg arg1)
         else {
             System_printf("Core %d: Static allocation failed with error: %d\n", MultiProc_self(), 
                                                                                 responseInfo.serviceState);
-        }            
-        
-        Rm_printResourceStatus(rmServerHandle);           
+        }                    
      
         memset((void *) &requestInfo, 0, sizeof(Rm_ServiceReqInfo));        
         requestInfo.type = Rm_service_RESOURCE_FREE;
@@ -739,9 +744,7 @@ void testRmTsk(UArg arg0, UArg arg1)
         else {
             System_printf("Core %d: Static allocation failed with error: %d\n", MultiProc_self(), 
                                                                                 responseInfo.serviceState);
-        }            
-        
-        Rm_printResourceStatus(rmServerHandle);     
+        }                
 
         memset((void *) &requestInfo, 0, sizeof(Rm_ServiceReqInfo));        
         requestInfo.type = Rm_service_RESOURCE_ALLOCATE_USE;