include/rm_loc.h

   1 /*
   2  *  file  rmloc.h
   3  *
   4  *  General private data structures of Resource Manager.
   5  *
   6  *  ============================================================================
   7  *      (C) Copyright 2012, Texas Instruments, Inc.
   8  *
   9  *  Redistribution and use in source and binary forms, with or without
  10  *  modification, are permitted provided that the following conditions
  11  *  are met:
  12  *
  13  *    Redistributions of source code must retain the above copyright
  14  *    notice, this list of conditions and the following disclaimer.
  15  *
  16  *    Redistributions in binary form must reproduce the above copyright
  17  *    notice, this list of conditions and the following disclaimer in the
  18  *    documentation and/or other materials provided with the
  19  *    distribution.
  20  *
  21  *    Neither the name of Texas Instruments Incorporated nor the names of
  22  *    its contributors may be used to endorse or promote products derived
  23  *    from this software without specific prior written permission.
  24  *
  25  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  26  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  27  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  28  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  29  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  30  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  31  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  32  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  33  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  34  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  35  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  36  *
  37  *  \par
  38 */
  39
  40 #ifndef RMLOC_H_
  41 #define RMLOC_H_
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47 /* RM external includes */
  48 #include <ti/drv/rm/rm_services.h>
  49 #include <ti/drv/rm/rm_policy.h>
  50 #include <ti/drv/rm/rm_transport.h>
  51
  52 #if 0
  53 /* RM permissions structure for CPPI DMA channels and flows */
  54 typedef struct
  55 {
  56     /** Array of pointers to each DMAs channel or flow permissions
  57        * From CPPI LLD - DMA 0 = SRIO
  58        *                          DMA 1 = AIF
  59        *                          DMA 2 = FFTC A
  60        *                          DMA 3 = FFTC B
  61        *                          DMA 4 = PASS
  62        *                          DMA 5 = QMSS
  63        *                          DMA 6 = FFTC C
  64        *                          DMA 7 = BCP
  65        *
  66        * Note: Some DMAs may not be supported based on the device */
  67     Rm_Perms *dmaPermPtrs[RM_CPPI_MAX_DMAS];
  68 } Rm_CppiChAndFlowPerms;
  69
  70 /* RM Cache Line Alignment Defines and Macros */
  71
  72 #define RM_MAX_CACHE_ALIGN 128  /* Maximum alignment for cache line size */
  73
  74 /* This macro generates compiler error if postulate is false, so
  75  * allows 0 overhead compile time size check.  This "works" when
  76  * the expression contains sizeof() which otherwise doesn't work
  77  * with preprocessor */
  78 #define RM_COMPILE_TIME_SIZE_CHECK(postulate)                         \
  79    do {                                                                 \
  80        typedef struct {                                                 \
  81          uint8_t NegativeSizeIfPostulateFalse[((int)(postulate))*2 - 1];\
  82        } PostulateCheck_t;                                              \
  83    }                                                                    \
  84    while (0)
  85
  86 /* Macro to pad out internal permission structures to multiple of RM_MAX_CACHE_ALIGN bytes
  87   * The macro prevent something else from being placed on same cache line as the permission.
  88   * arrays.  Note that pad[0] is illegal, so must add full RM_MAX_CACHE_ALIGN if structure
  89   * is already padded by chance. */
  90 #define RM_ALIGN_PERMISSIONS_ARRAY(numElements, permStructType) ( \
  91      (((sizeof(permStructType) * (numElements)) % RM_MAX_CACHE_ALIGN) == 0) ? (numElements) : \
  92      ((numElements) + \
  93        (RM_MAX_CACHE_ALIGN - \
  94          ((sizeof(permStructType) * (numElements)) % RM_MAX_CACHE_ALIGN))/sizeof(permStructType)))
  95
  96 /* RM Global Sync Object (unpadded) */
  97 typedef struct
  98 {
  99     /** Rm_init/Rm_start synchronization object. */
 100     uint8_t globalSyncObj;
 101 } Rm_Sync_Obj_Unpadded;
 102
 103 /* RM Global Sync Object (padded) */
 104 typedef struct
 105 {
 106     /** Data structure without padding, so sizeof() can compute padding */
 107     Rm_Sync_Obj_Unpadded obj;
 108     /** Pad out to end of RM_MAX_CACHE_ALIGN bytes to prevent something else
 109      * from being placed on same cache line as Rm_Synci_Obj.  Note that
 110      * pad[0] is illegal, so must add full RM_MAX_CACHE_ALIGN if structure
 111      * is already padded by chance. */
 112     uint8_t  pad[RM_MAX_CACHE_ALIGN -
 113                        (sizeof(Rm_Sync_Obj_Unpadded) % RM_MAX_CACHE_ALIGN)];
 114 } Rm_Sync_Obj;
 115 #endif
 116
 117 /** Maximum size of a transmittable RM policy in bytes */
 118 #define RM_MAX_POLICY_SIZE_BYTES (64)  // Placeholder: This will change
 119                                        // during development
 120
 121 /** Pointer to RM instance's transport routing map */
 122 typedef void *Rm_TransportRouteMap;
 123
 124 /** Pointer to RM instance's transaction queue */
 125 typedef void *Rm_TransactionQueue;
 126
 127 /**
 128  * @brief RM transaction details values.  Details values provide more fine-grained
 129  *        information regarding a transaction request or response
 130  */
 131 typedef enum {
 132     /** Transaction is being processed */
 133     Rm_transactionState_PROCESSING = 0,
 134     /** Transaction is waiting for response from higher level agent */
 135     Rm_transactionState_AWAITING_RESPONSE = 1,
 136     /** Transaction has been approved */
 137     Rm_transactionState_RESOURCE_APPROVED = 2,
 138     /** Transaction has been denied */
 139     Rm_transactionState_RESOURCE_DENIED = 3
 140 } Rm_TransactionState;
 141
 142 /**
 143  * @brief RM protocol packet resource information
 144  */
 145 typedef struct {
 146     /** Resource name of resource affected by command */
 147     char name[RM_RESOURCE_NAME_MAX_CHARS];
 148     /** If applicable, start of resource range affected by command.  If
 149      *  RM_RESOURCE_UNSPECIFIED is assigned the higher level RM agent*/
 150     int32_t base;
 151     /** If applicable, range of specified resource, starting from base, affected by command */
 152     uint32_t range;
 153     /** If applicable, the alignment of the resource affected by the command */
 154     int32_t alignment;
 155     /** If applicable, the NameServer name assigned to the specified
 156      *  resource.  Used for commands centering on RM NameServer actions */
 157     char nsName[RM_RESOURCE_NAME_MAX_CHARS];
 158 } Rm_ResourceInfo;
 159
 160 /**
 161  * @brief RM transactions are the internalized version of service requests received
 162  *        from components and RM commands received from other RM instances.
 163  *        Transactions that cannot immediately be serviced are placed in the RM
 164  *        instance's transaction queue.
 165  */
 166 typedef struct {
 167     /** Transaction service type */
 168     Rm_ServiceType type;
 169     /** ID of transaction.  Maps to the RM protocol packet ID when forwarding
 170      *  RM requests or received RM responses. */
 171     uint32_t id;
 172     /** Name of the RM instance the transaction originated from */
 173     char sourceInstName[RM_INSTANCE_NAME_MAX_CHARS];
 174     /** Transaction's associated callback function */
 175     Rm_ServiceCallback callback;
 176     /** Transaction state */
 177     Rm_TransactionState state;
 178     /** Transaction details.  Provides detailed request/response codes such as
 179      *  resource denial reasons.  The codes are externally visible and tracked
 180      *  in rmservices.h */
 181     int32_t details;
 182     /** Resource information */
 183     Rm_ResourceInfo resourceInfo;
 184     /** Link to the next transaction in the queue */
 185     void *nextTransaction;
 186 } Rm_Transaction;
 187
 188 /**
 189  * @brief Transaction receipt contains transaction result information that is passed
 190  *        back to the entity that was the source of the transaction.  The source can be
 191  *        a component that requested a service or a RM instance that sent a command.
 192  */
 193 typedef struct {
 194     /** Result of the requested service.  Service result types are explained in the
 195      *  Rm_services.h header */
 196     int32_t serviceResult;
 197     /** If RM cannot provide a result to the service immediately a service ID will
 198      *  be provided to the service requester.  The service ID should be used by the
 199      *  requester to map RM service responses received via the callback function
 200      *  provided to RM at the time of requesting the service */
 201     uint32_t serviceId;
 202     /** Base value of resource affected by the service request if RM immediately handles
 203      *  the request */
 204     uint32_t resourceBase;
 205     /** Range of resource starting at resourceBase affected by the service request if RM
 206      *  immediately handles the request */
 207     uint32_t resourceRange;
 208 } Rm_TransactionReceipt;
 209
 210 typedef enum {
 211     /** running */
 212     RM_state_IDLE = 0,
 213     /** handling request */
 214     RM_state_HANDLING_REQUEST = 1
 215     /** etc...flesh all these out later will need states for the different alloc, free, request/response handlers */
 216 } Rm_State;
 217
 218 typedef struct {
 219     char name[RM_INSTANCE_NAME_MAX_CHARS];
 220     Rm_InstType instType;
 221     Rm_State instState;  // IS THIS NEEDED???
 222     bool registeredWithDelegateOrServer;
 223     Rm_PolicyHandle instPolicy;  /* Client Delegate only? */
 224     /* RM instance transport parameters */
 225     Rm_TransportRouteMap routeMap;
 226     /* RM Transaction sequence number counter */
 227     uint32_t transactionSeqNum;
 228     /* RM transaction queue */
 229     Rm_TransactionQueue transactionQueue;
 230     /* Transport API function pointers - not global in case application wants to
 231       * hook up different transports to RM */
 232     Rm_TransportCallouts transport;
 233 } Rm_Inst;
 234
 235 Rm_Transaction *Rm_transactionQueueAdd(Rm_Inst *rmInst, uint32_t transactionId);
 236 Rm_Transaction *Rm_transactionQueueFind(Rm_Inst *rmInst, uint32_t transactionId);
 237 int32_t Rm_transactionQueueDelete(Rm_Inst *rmInst, uint32_t transactionId);
 238 uint32_t Rm_transactionGetSequenceNum(Rm_Inst *rmInst);
 239
 240 void Rm_transactionProcessor (Rm_Inst *rmInst, Rm_Transaction *transaction,
 241                               Rm_TransactionReceipt *receipt);
 242
 243
 244 #ifdef __cplusplus
 245 }
 246 #endif
 247
 248 #endif /* RMLOC_H_ */
 249