edma3_rm.h

vicp做为dm6446上的硬件加速器

} EDMA3_RM_ResDesc;

/* @} Edma3ResType */


/**
 * \fn  EDMA3_RM_Result EDMA3_RM_registerTccCb(EDMA3_RM_Handle hEdmaResMgr,
 *      const EDMA3_RM_ResDesc *channelObj, unsigned int tcc,
 *      EDMA3_RM_TccCallback tccCb, void *cbData);
 * \brief   Register Interrupt / Completion Handler for a given TCC.
 *
 * This function enables the interrupts in IESR/IESRH, only if the callback
 * function provided by the user is NON-NULL. Moreover, if a call-back function
 * is already registered against that TCC, the API fails with the error code
 * EDMA3_RM_E_CALLBACK_ALREADY_REGISTERED. For a NULL callback function,
 * this API returns error.
 *
 * \param   hEdmaResMgr         [IN]    Handle to the previously opened
 *                                      EDMA3 Resource Manager Instance
 * \param   channelObj          [IN]    Channel ID and type (DMA or QDMA
 *                                      Channel), allocated earlier, and
 *                                      corresponding to which a callback
 *                                      function needs to be registered
 *                                      against the associated TCC.
 * \param   tcc                 [IN]    TCC against which the handler needs to
 *                                      be registered.
 * \param   tccCb               [IN]    The Callback function to be registered
 *                                      against the TCC.
 * \param   cbData              [IN]    Callback data to be passed while calling
 *                                      the callback function.
 *
 * \return  EDMA3_RM_SOK or EDMA3_RM Error Code
 *
 * \note    This function is re-entrant for unique tcc values. It is non-
 *          re-entrant for same tcc value.
 */
EDMA3_RM_Result EDMA3_RM_registerTccCb(EDMA3_RM_Handle hEdmaResMgr,
                    const EDMA3_RM_ResDesc *channelObj,
                    unsigned int tcc,
                    EDMA3_RM_TccCallback tccCb,
                    void *cbData);


/**
 * \fn      EDMA3_RM_Result EDMA3_RM_unregisterTccCb(EDMA3_RM_Handle
 *          hEdmaResMgr, const EDMA3_RM_ResDesc *channelObj);
 * \brief   Unregister the previously registered callback function against a
 *          DMA/QDMA channel.
 *
 * This function unregisters the previously registered callback function against
 * a DMA/QDMA channel by removing any stored callback function. Moreover, it
 * clears the interrupt enable register (IESR/IESRH) by writing to the IECR/
 * IECRH register, for the TCC associated with that particular channel.
 *
 * \param   hEdmaResMgr         [IN]    Handle to the previously opened
 *                                      EDMA3 Resource Manager Instance
 * \param   channelObj          [IN]    Channel ID and type, allocated earlier
 *                                      (DMA or QDMA Channel ONLY), and
 *                                      corresponding to which a TCC is there.
 *                                      Against that TCC, the callback needs
 *                                      to be un-registered.
 *
 * \return  EDMA3_RM_SOK or EDMA3_RM Error Code.
 *
 * \note    This function is re-entrant for unique (channelObj->type +
 *          channelObj->resId) combination. It is non-re-entrant for same
 *          channelObj Resource.
 */
EDMA3_RM_Result EDMA3_RM_unregisterTccCb(EDMA3_RM_Handle hEdmaResMgr,
                    const EDMA3_RM_ResDesc *channelObj);

/* @} Edma3RMIntrMgrChannel */

/* @} Edma3RMIntrMgrMain */



/**
 * \defgroup Edma3RMMain  Interface Definition for EDMA3 Resource Manager Layer
 *
 * Top-level Encapsulation of all documentation for EDMA3 Resource Manager Layer
 *
 * @{
 */


/*---------------------------------------------------------------------------*/
/*------------------Usage Guidelines Start-----------------------------------*/
/*---------------------------------------------------------------------------*/

/**
 * \defgroup Edma3RMUsage EDMA3 Resource Manager Usage Guidelines
 *
 * Guidelines for typical usage of EDMA3 Resource Manager.
 *
 * @{
 */

/**
  \brief Usage of Resource Manager.

    -# 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);
    -# 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

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

            -# 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).

            -# 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 );

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

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

            -# initParam.rmInstInitConfig->ownDmaChannels[] =
               The bitmap(s) which indicate the DMA channels owned by this
               instance of the Resource Manager\n
               E.g. A '1' at bit position 24 indicates that this instance of
               the Resource Manager owns DMA Channel Id 24\n
               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.
            -# initParam.rmInstInitConfig->ownQdmaChannels[] =
               The bitmap(s) which indicate the QDMA channels owned by this
               instance of the Resource Manager\n
            -# initParam.rmInstInitConfig->ownPaRAMSets[] =
               The bitmap(s) which indicate the PaRAM Sets owned by this
               instance of the Resource Manager\n
            -# initParam.rmInstInitConfig->ownTccs[] =
               The bitmap(s) which indicate the TCCs owned by this
               instance of the Resource Manager\n

            -# initParam.rmInstInitConfig->resvdDmaChannels[] =
               The bitmap(s) which indicate the DMA channels reserved by this
               instance of the Resource Manager\n
               E.g. A '1' at bit position 24 indicates that this instance of
               the Resource Manager reserves Channel Id 24\n
               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.\n
            -# initParam.rmInstInitConfig->resvdQdmaChannels[] =
               The bitmap(s) which indicate the QDMA channels reserved by this
               instance of the Resource Manager\n
               E.g. A '1' at bit position 1 indicates that this instance of
               the Resource Manager reserves QDMA Channel Id 1\n
               These channels are reserved for some specific purpose,
               these are not given to 'EDMA3_RM_QDMA_CHANNEL_ANY'
               or 'EDMA3_RM_RES_ANY' request\n
            -# initParam.rmInstInitConfig->resvdPaRAMSets[] =
               PaRAM Sets which are reserved by this Region;
            -# initParam.rmInstInitConfig->resvdTccs[] =
               TCCs which are reserved by this Region;

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

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

    -# 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.\n\n
            - dmaChId = 5;\n\n
            - resObj.type = EDMA3_RM_RES_DMA_CHANNEL;
            - resObj.resId = dmaChId;
            - result = EDMA3_RM_allocResource(hRes, &resObj);\n\n

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

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

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

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

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

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

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

        - 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); \n\n

        - 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); \n\n

        - 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); \n\n

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

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

        - 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); \n\n

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

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

        - 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; \n\n

        - 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;\n\n

        - 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);