Error Codes
[Interface Definition for EDMA3 Resource Manager Layer]

Usage of Resource Manager. More...

Defines
#define	EDMA3_RM_E_BASE   (-155)
#define	EDMA3_RM_E_OBJ_NOT_DELETED   (EDMA3_RM_E_BASE)
#define	EDMA3_RM_E_OBJ_NOT_CLOSED   (EDMA3_RM_E_BASE-1)
#define	EDMA3_RM_E_OBJ_NOT_OPENED   (EDMA3_RM_E_BASE-2)
#define	EDMA3_RM_E_INVALID_PARAM   (EDMA3_RM_E_BASE-3)
#define	EDMA3_RM_E_RES_ALREADY_FREE   (EDMA3_RM_E_BASE-4)
#define	EDMA3_RM_E_RES_NOT_OWNED   (EDMA3_RM_E_BASE-5)
#define	EDMA3_RM_E_SPECIFIED_RES_NOT_AVAILABLE   (EDMA3_RM_E_BASE-6)
#define	EDMA3_RM_E_ALL_RES_NOT_AVAILABLE   (EDMA3_RM_E_BASE-7)
#define	EDMA3_RM_E_INVALID_STATE   (EDMA3_RM_E_BASE-8)
#define	EDMA3_RM_E_MAX_RM_INST_OPENED   (EDMA3_RM_E_BASE-9)
#define	EDMA3_RM_E_RM_MASTER_ALREADY_EXISTS   (EDMA3_RM_E_BASE-10)
#define	EDMA3_RM_E_CALLBACK_ALREADY_REGISTERED   (EDMA3_RM_E_BASE-11)
#define	EDMA3_RM_E_SEMAPHORE   (EDMA3_RM_E_BASE-12)
#define	EDMA3_RM_E_FEATURE_UNSUPPORTED   (EDMA3_RM_E_BASE-13)
#define	EDMA3_RM_E_RES_NOT_ALLOCATED   (EDMA3_RM_E_BASE-14)

---

Detailed Description

Usage of Resource Manager.

1. Create Resource Manager Object (one for each EDMA3 hardware instance)
   • EDMA3_RM_Result result = EDMA3_RM_SOK;
   • unsigned int edma3HwInstanceId = 0u;
   • EDMA3_RM_GblConfigParams *gblCfgParams = NULL;
   • Init-time Configuration structure for EDMA3 controller, to provide Global SoC specific Information. This could be NULL also. In that case, static configuration will be taken.
   • result = EDMA3_RM_create (edma3HwInstanceId, gblCfgParams, NULL);
2. Open Resource Manager Instance
   • Steps
     • EDMA3_RM_Param initParam;
     • unsigned int resMgrIdx = 0;
     • EDMA3_RM_Handle hRes = NULL;
     • unsigned int mappedPaRAMId;
     • EDMA3_OS_SemAttrs semAttrs = {EDMA3_OS_SEMTYPE_FIFO, NULL};
     • EDMA3_RM_Result edma3Result; -To get the error code while opening Resource Manager instance

1. initParam.regionId = Region Id e.g. (EDMA3_RM_RegionId)0u OR (EDMA3_RM_RegionId)1u

1. initParam.isMaster = TRUE/FALSE (Whether this EDMA3 RM instance is Master or not. The EDMA3 Shadow Region tied to the Master RM Instance will ONLY receive the EDMA3 interrupts (error or completion), if enabled).

1. initParam.rmSemHandle = EDMA3 RM Instance specific semaphore handle. It should be provided by the user for proper sharing of resources.
   • edma3Result = edma3OsSemCreate(1, &semAttrs, &initParam.rmSemHandle );

1. initParam.regionInitEnable = TRUE/FALSE (Whether init of Region Specifc registers should be done or not?);

1. initParam.gblerrCbParams.gblerrCb = Instance wide callback function to catch non-channel specific errors
2. initParam.gblerrCbParams.gblerrData = Data to be passed to global error callback function, gblerrCb.

1. initParam.rmInstInitConfig->ownDmaChannels[] = The bitmap(s) which indicate the DMA channels owned by this instance of the Resource Manager
   E.g. A '1' at bit position 24 indicates that this instance of the Resource Manager owns DMA Channel Id 24
   Later when a request is made based on a particular Channel Id, the Resource Manager will check first if it owns that channel. If it doesnot own it, Resource Manager returns error EDMA3_RM_E_RES_NOT_OWNED.
2. initParam.rmInstInitConfig->ownQdmaChannels[] = The bitmap(s) which indicate the QDMA channels owned by this instance of the Resource Manager
   
3. initParam.rmInstInitConfig->ownPaRAMSets[] = The bitmap(s) which indicate the PaRAM Sets owned by this instance of the Resource Manager
   
4. initParam.rmInstInitConfig->ownTccs[] = The bitmap(s) which indicate the TCCs owned by this instance of the Resource Manager
   

1. initParam.rmInstInitConfig->resvdDmaChannels[] = The bitmap(s) which indicate the DMA channels reserved by this instance of the Resource Manager
   E.g. A '1' at bit position 24 indicates that this instance of the Resource Manager reserves Channel Id 24
   These channels are reserved and may be mapped to HW events, these are not given to 'EDMA3_RM_DMA_CHANNEL_ANY' or 'EDMA3_RM_RES_ANY' requests.
   
2. initParam.rmInstInitConfig->resvdQdmaChannels[] = The bitmap(s) which indicate the QDMA channels reserved by this instance of the Resource Manager
   E.g. A '1' at bit position 1 indicates that this instance of the Resource Manager reserves QDMA Channel Id 1
   These channels are reserved for some specific purpose, these are not given to 'EDMA3_RM_QDMA_CHANNEL_ANY' or 'EDMA3_RM_RES_ANY' request
   
3. initParam.rmInstInitConfig->resvdPaRAMSets[] = PaRAM Sets which are reserved by this Region;
4. initParam.rmInstInitConfig->resvdTccs[] = TCCs which are reserved by this Region;

-hRes = EDMA3_RM_open (instId, &initParam, &edma3Result);

1. Register Interrupt Handlers for various interrupts like transfer completion interrupt, CC error interrupt, TC error interrupts etc, if required.

1. Resource Management APIs:
   • EDMA3_RM_ResDesc resObj;
   • EDMA3_RM_Result result;
   • unsigned int dmaChId;
   • unsigned int qdmaChId;
   • unsigned int paRAMId;
   • unsigned int tcc;
   • EDMA3_RM_QdmaTrigWord trigword;
   • EDMA3_RM_TccCallback tccCb;
   • void *cbData;

• Use Case 1: Request specific DMA Channel, say EDMA Channel 5.
  
  
  • dmaChId = 5;
    
    
  • resObj.type = EDMA3_RM_RES_DMA_CHANNEL;
  • resObj.resId = dmaChId;
  • result = EDMA3_RM_allocResource(hRes, &resObj);
    
    

• Use Case 2: Request any available DMA Channel.
  
  
  • dmaChId = EDMA3_RM_RES_ANY;
    
    
  • resObj.type = EDMA3_RM_RES_DMA_CHANNEL;
  • resObj.resId = dmaChId;
  • result = EDMA3_RM_allocResource(hRes, &resObj);
    
    
  • dmaCh1Id = resObj.resId;
    
    

• Use Case 3: Request a specific QDMA Channel, say QDMA Channel 0.
  
  
  • qdmaChId = 0;
    
    
  • resObj.type = EDMA3_RM_RES_QDMA_CHANNEL;
  • resObj.resId = qdmaChId;
  • result = EDMA3_RM_allocResource(hRes, &resObj);
    
    

• Use Case 4: Request any available QDMA Channel.
  
  
  • qdmaChId = EDMA3_RM_RES_ANY;
    
    
  • resObj.type = EDMA3_RM_RES_QDMA_CHANNEL;
  • resObj.resId = qdmaChId;
  • result = EDMA3_RM_allocResource(hRes, &resObj);
    
    
  • qdmaChId = resObj.resId;
    
    

• Use Case 5: Request specific Parameter RAM Set, say 20.
  
  
  • paRAMId = 20;
    
    
  • resObj.type = EDMA3_RM_RES_PARAM_SET;
  • resObj.resId = paRAMId;
  • result = EDMA3_RM_allocResource(hRes, &resObj);
    
    

• Use Case 6: Request any available Parameter RAM Set.
  
  
  • paRAMId = EDMA3_RM_RES_ANY;
    
    
  • resObj.type = EDMA3_RM_RES_PARAM_SET;
  • resObj.resId = paRAMId;
  • result = EDMA3_RM_allocResource(hRes, &resObj);
    
    
  • paRAMId = resObj.resId;
    
    

• Use Case 7: Request a specific TCC, say TCC 35.
  
  
  • tcc = 35;
    
    
  • resObj.type = EDMA3_RM_RES_TCC;
  • resObj.resId = tcc;
  • result = EDMA3_RM_allocResource(hRes, &resObj);
    
    

• Use Case 8: Request any available TCC.
  
  
  • tcc = EDMA3_RM_RES_ANY;
    
    
  • resObj.type = EDMA3_RM_RES_TCC;
  • resObj.resId = tcc;
  • result = EDMA3_RM_allocResource(hRes, &resObj);
    
    
  • tcc = resObj.resId;
    
    

• Use Case 9: Free the already allocated DMA channel
  • resObj.type = EDMA3_RM_RES_DMA_CHANNEL;
  • resObj.resId = dmaChId;
  • result = EDMA3_RM_freeResource(hRes, &resObj);
    
    

• Use Case 10: Free the already allocated QDMA channel
  • resObj.type = EDMA3_RM_RES_QDMA_CHANNEL;
  • resObj.resId = qdmaChId;
  • result = EDMA3_RM_freeResource(hRes, &resObj);
    
    

• Use Case 11: Free the already allocated PaRAM Set
  • resObj.type = EDMA3_RM_RES_PARAM_SET;
  • resObj.resId = paRAMId;
  • result = EDMA3_RM_freeResource(hRes, &resObj);
    
    

• Use Case 12: Free the already allocated TCC
  • resObj.type = EDMA3_RM_RES_TCC;
  • resObj.resId = tcc;
  • result = EDMA3_RM_freeResource(hRes, &resObj);
    
    

• Use Case 13: Bind DMA Channel and a PaRAM Set
  • result = EDMA3_RM_mapEdmaChannel (hRes,dmaChId,paRAMId);
    
    

• Use Case 14: Bind QDMA Channel and a PaRAM Set. Also, specify the Trigger word for the QDMA channel.
  • result = EDMA3_RM_mapQdmaChannel (hRes, qdmaChId, paRAMId, trigword);
    
    

• Use Case 15: Register a Callback function associated with a TCC
  
  
  • result = EDMA3_RM_registerTccCb (hRes,tcc,tccCb,cbData);
    
    

• Use Case 16: Unregister a Callback function associated with a TCC
  
  
  • result = EDMA3_RM_unregisterTccCb (hRes,tcc);
    
    

• Use Case 17: Allocate a logical (ANY) DMA channel. It will also allocate PaRAM Set and TCC alongwitht a DMA channel.
  • resObj.type = EDMA3_RM_RES_DMA_CHANNEL;
  • resObj.resId = EDMA3_RM_DMA_CHANNEL_ANY;
  • result = EDMA3_RM_allocLogicalChannel (hRes, &resObj, paRAMId, tcc);
  • dmaCh1Id = resObj.resId;
    
    

• Use Case 18: Allocate a logical (ANY) QDMA channel. It will also allocate PaRAM Set and TCC alongwitht a QDMA channel.
  • resObj.type = EDMA3_RM_RES_QDMA_CHANNEL;
  • resObj.resId = EDMA3_RM_QDMA_CHANNEL_ANY;
  • result = EDMA3_RM_allocLogicalChannel (hRes, &resObj, paRAMId, tcc);
  • qdmaChId = resObj.resId;
    
    

• Use Case 19: Allocate a Link channel. Link channel is nothing but a PaRAM Set, used for Linking purpose specifically. The allocated PaRAM Set is returned in the resObj.resId value.
  • resObj.type = EDMA3_RM_RES_PARAM_SET;
  • resObj.resId = EDMA3_RM_PARAM_ANY;
  • result = EDMA3_RM_allocLogicalChannel (hRes, &resObj, NULL, NULL);

• Use Case 20: Free the previously allocated Link channel. It will free the PaRAM Set used for linking.
  • result = EDMA3_RM_freeLogicalChannel (hRes, &resObj);

• Use Case 21: Free the previously allocated logical DMA channel. It will also free the associated PaRAM Set and TCC.
  • resObj.type = EDMA3_RM_RES_DMA_CHANNEL;
  • resObj.resId = dmaCh1Id;
  • result = EDMA3_RM_freeLogicalChannel (hRes, &resObj);

• Use Case 22: Free the previously allocated logical QDMA channel. It will also free the associated PaRAM Set and TCC.
  • resObj.type = EDMA3_RM_RES_QDMA_CHANNEL;
  • resObj.resId = qdmaChId;
  • result = EDMA3_RM_freeLogicalChannel (hRes, &resObj);

1. Close Resource Manager Instance
   • Steps
     • EDMA3_RM_Result edma3Result = EDMA3_RM_SOK;

• Unregister Interrupt Handlers first, if previously registered.
• Delete the semaphore created during RM Instance Opening.
  • edma3Result = edma3OsSemDelete (rmSemHandle);
• Close the EDMA3 RM Instance
  • edma3Result = EDMA3_RM_close (hRes, NULL);

1. Delete Resource Manager Object
   • Steps
     • EDMA3_RM_Result edma3Result = EDMA3_RM_SOK;
     • unsigned int edmaInstanceId = 0;

• edma3Result = EDMA3_RM_delete (edmaInstanceId, NULL);

Error Codes returned by the EDMA3 Resource Manager Layer

---

Define Documentation

#define EDMA3_RM_E_ALL_RES_NOT_AVAILABLE   (EDMA3_RM_E_BASE-7)

No Resource of specified type is available

Referenced by EDMA3_RM_allocResource().

#define EDMA3_RM_E_BASE   (-155)

Resource Manager Error Codes base define

#define EDMA3_RM_E_CALLBACK_ALREADY_REGISTERED   (EDMA3_RM_E_BASE-11)

Callback function already registered.

Referenced by EDMA3_RM_registerTccCb().

#define EDMA3_RM_E_FEATURE_UNSUPPORTED   (EDMA3_RM_E_BASE-13)

Hardware feature NOT supported

Referenced by EDMA3_RM_mapEdmaChannel().

#define EDMA3_RM_E_INVALID_PARAM   (EDMA3_RM_E_BASE-3)

Invalid Parameter passed to API

Referenced by EDMA3_RM_allocContiguousResource(), EDMA3_RM_allocLogicalChannel(), EDMA3_RM_allocResource(), EDMA3_RM_checkAndClearTcc(), EDMA3_RM_close(), EDMA3_RM_create(), EDMA3_RM_delete(), EDMA3_RM_freeContiguousResource(), EDMA3_RM_freeLogicalChannel(), EDMA3_RM_freeResource(), EDMA3_RM_getBaseAddress(), EDMA3_RM_getCCRegister(), EDMA3_RM_getGblConfigParams(), EDMA3_RM_getInstanceInitCfg(), EDMA3_RM_getPaRAM(), EDMA3_RM_getPaRAMPhyAddr(), EDMA3_RM_Ioctl(), EDMA3_RM_mapEdmaChannel(), EDMA3_RM_mapQdmaChannel(), EDMA3_RM_open(), EDMA3_RM_registerTccCb(), EDMA3_RM_setCCRegister(), EDMA3_RM_setPaRAM(), EDMA3_RM_unregisterTccCb(), and EDMA3_RM_waitAndClearTcc().

#define EDMA3_RM_E_INVALID_STATE   (EDMA3_RM_E_BASE-8)

Invalid State of EDMA3 RM Obj

Referenced by EDMA3_RM_delete(), and EDMA3_RM_open().

#define EDMA3_RM_E_MAX_RM_INST_OPENED   (EDMA3_RM_E_BASE-9)

Maximum no of Res Mgr Instances already Opened

Referenced by EDMA3_RM_open().

#define EDMA3_RM_E_OBJ_NOT_CLOSED   (EDMA3_RM_E_BASE-1)

Resource Manager Object Not Closed yet. So the object cannot be deleted.

Referenced by EDMA3_RM_delete().

#define EDMA3_RM_E_OBJ_NOT_DELETED   (EDMA3_RM_E_BASE)

Resource Manager Object Not Deleted yet. So the object cannot be created.

Referenced by EDMA3_RM_create().

#define EDMA3_RM_E_OBJ_NOT_OPENED   (EDMA3_RM_E_BASE-2)

Resource Manager Object Not Opened yet So the object cannot be closed.

Referenced by EDMA3_RM_close().

#define EDMA3_RM_E_RES_ALREADY_FREE   (EDMA3_RM_E_BASE-4)

Resource requested for freeing is already free

Referenced by EDMA3_RM_freeResource().

#define EDMA3_RM_E_RES_NOT_ALLOCATED   (EDMA3_RM_E_BASE-14)

EDMA3 Resource NOT allocated

Referenced by EDMA3_RM_mapEdmaChannel(), and EDMA3_RM_mapQdmaChannel().

#define EDMA3_RM_E_RES_NOT_OWNED   (EDMA3_RM_E_BASE-5)

Resource requested for allocation/freeing is not owned

Referenced by EDMA3_RM_allocContiguousResource(), EDMA3_RM_allocResource(), and EDMA3_RM_freeResource().

#define EDMA3_RM_E_RM_MASTER_ALREADY_EXISTS   (EDMA3_RM_E_BASE-10)

More than one Res Mgr Master Instance NOT supported. Only 1 master can exist.

Referenced by EDMA3_RM_open().

#define EDMA3_RM_E_SEMAPHORE   (EDMA3_RM_E_BASE-12)

Semaphore related error

#define EDMA3_RM_E_SPECIFIED_RES_NOT_AVAILABLE   (EDMA3_RM_E_BASE-6)

Resource is not available

Referenced by EDMA3_RM_allocContiguousResource(), and EDMA3_RM_allocResource().