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 has been approved */
 135     Rm_transactionState_TRANSACTION_APPROVED = 1,
 136     /** Transaction has been denied */
 137     Rm_transactionState_TRANSACTION_DENIED = 2
 138 } Rm_TransactionState;
 139
 140 /**
 141  * @brief RM protocol packet resource information
 142  */
 143 typedef struct {
 144     /** Resource name of resource affected by command */
 145     char name[RM_RESOURCE_NAME_MAX_CHARS];
 146     /** If applicable, start of resource range affected by command.  If
 147      *  RM_RESOURCE_UNSPECIFIED is assigned the higher level RM agent*/
 148     int32_t base;
 149     /** If applicable, range of specified resource, starting from base, affected by command */
 150     uint32_t range;
 151     /** If applicable, the alignment of the resource affected by the command */
 152     int32_t alignment;
 153     /** If applicable, the NameServer name assigned to the specified
 154      *  resource.  Used for commands centering on RM NameServer actions */
 155     char nsName[RM_RESOURCE_NAME_MAX_CHARS];
 156 } Rm_ResourceInfo;
 157
 158 /**
 159  * @brief RM transactions are the internalized version of service requests received
 160  *        from components and RM commands received from other RM instances.
 161  *        Transactions that cannot immediately be serviced are placed in the RM
 162  *        instance's transaction queue.  The transactions track all service
 163  *        requests within the RM infrastructure.
 164  */
 165 typedef struct {
 166     /** Transaction service type */
 167     Rm_ServiceType type;
 168     /** Local ID of the transaction. */
 169     uint32_t localId;
 170     /** ID of transaction on lower level RM instance that generated the
 171      *  packet that resulted in the creation of the transaction.  The
 172      *  originating ID will be placed in the transaction's response packet
 173      *  to the lower level RM instance.  The lower level RM instance will
 174      *  match the response packet with the originating request using the ID */
 175     uint32_t remoteOriginatingId;
 176     /** Name of the RM instance the transaction originated from */
 177     char sourceInstName[RM_INSTANCE_NAME_MAX_CHARS];
 178     /** Transaction's associated callback function */
 179     Rm_ServiceCallback callback;
 180     /** Transaction state.  The codes are externally visible and tracked
 181      *  in rmservices.h */
 182     int32_t state;
 183     /** Resource information */
 184     Rm_ResourceInfo resourceInfo;
 185     /** Link to the next transaction in the queue */
 186     void *nextTransaction;
 187 } Rm_Transaction;
 188
 189 typedef struct {
 190     char name[RM_INSTANCE_NAME_MAX_CHARS];
 191     Rm_InstType instType;
 192     bool registeredWithDelegateOrServer;
 193     Rm_PolicyHandle instPolicy;  /* Client Delegate only? */
 194     /* RM instance transport parameters */
 195     Rm_TransportRouteMap routeMap;
 196     /* RM Transaction sequence number counter */
 197     uint32_t transactionSeqNum;
 198     /* RM transaction queue */
 199     Rm_TransactionQueue transactionQueue;
 200     /* Transport API function pointers - not global in case application wants to
 201       * hook up different transports to RM */
 202     Rm_TransportCallouts transport;
 203 } Rm_Inst;
 204
 205 Rm_Transaction *Rm_transactionQueueAdd(Rm_Inst *rmInst);
 206 Rm_Transaction *Rm_transactionQueueFind(Rm_Inst *rmInst, uint32_t transactionId);
 207 int32_t Rm_transactionQueueDelete(Rm_Inst *rmInst, uint32_t transactionId);
 208 uint32_t Rm_transactionGetSequenceNum(Rm_Inst *rmInst);
 209
 210 void Rm_transactionProcessor (Rm_Inst *rmInst, Rm_Transaction *transaction);
 211
 212 #ifdef __cplusplus
 213 }
 214 #endif
 215
 216 #endif /* RMLOC_H_ */
 217