edma3_rm.h

vicp做为dm6446上的硬件加速器

 * This assignment should also ensure that the same resource is not assigned
 * to more than one shadow regions (unless desired in that way). Any assignment
 * not following the above mentioned approach may have catastrophic
 * consequences.
 *
 *
 * Reserved resources:
 * *******************
 *
 * During EDMA3 RM initialization, user can reserve some of the EDMA3 resources
 * for future use, by specifying which resources to reserve in the configuration
 * data structure. These (critical) resources are reserved in advance so that
 * they should not be allocated to someone else and thus could be used in
 * future for some specific purpose.
 *
 * User can request different EDMA3 resources using two methods:
 * a) By passing the resource type and the actual resource id,
 * b) By passing the resource type and ANY as resource id
 *
 * For e.g. to request DMA channel 31, user will pass 31 as the resource id.
 * But to request ANY available DMA channel (mainly used for memory-to-memory
 * data transfer operations), user will pass EDMA3_DRV_DMA_CHANNEL_ANY as the
 * resource id.
 *
 * During initialization, user may have reserved some of the DMA channels for
 * some specific purpose (mainly for peripherals using EDMA). These reserved
 * DMA channels then will not be returned when user requests ANY as the
 * resource id.
 *
 * Same logic applies for QDMA channels and TCCs.
 *
 * For PaRAM Set, there is one difference. If the DMA channels are one-to-one
 * tied to their respective PaRAM Sets (i.e. user cannot 'choose' the PaRAM Set
 * for a particular DMA channel), EDMA3 RM automatically reserves all those
 * PaRAM Sets which are tied to the DMA channels. Then those PaRAM Sets would
 * not be returned when user requests for ANY PaRAM Set (specifically for
 * linking purpose). This is done in order to avoid allocating the PaRAM Set,
 * tied to a particular DMA channel, for linking purpose. If this constraint is
 * not there, that DMA channel thus could not be used at all, because of the
 * unavailability of the desired PaRAM Set.
 */
typedef struct
{
    /** PaRAM Sets owned by the EDMA3 RM Instance. */
    unsigned int        ownPaRAMSets[EDMA3_MAX_PARAM_DWRDS];

    /** DMA Channels owned by the EDMA3 RM Instance. */
    unsigned int        ownDmaChannels[EDMA3_MAX_DMA_CHAN_DWRDS];

    /** QDMA Channels owned by the EDMA3 RM Instance. */
    unsigned int        ownQdmaChannels[EDMA3_MAX_QDMA_CHAN_DWRDS];

    /** TCCs owned by the EDMA3 RM Instance. */
    unsigned int        ownTccs[EDMA3_MAX_TCC_DWRDS];

    /**
     * \brief   Reserved PaRAM Sets
     *
     * PaRAM Sets reserved during initialization for future use. These will not
     * be given when user requests for ANY available PaRAM Set using
     * 'EDMA3_RM_PARAM_ANY' as resource/channel id.
     */
    unsigned int        resvdPaRAMSets[EDMA3_MAX_PARAM_DWRDS];

    /**
     * \brief   Reserved DMA channels
     *
     * DMA channels reserved during initialization for future use. These will
     * not be given when user requests for ANY available DMA channel using
     * 'EDMA3_RM_DMA_CHANNEL_ANY' as resource/channel id.
     */
    unsigned int        resvdDmaChannels[EDMA3_MAX_DMA_CHAN_DWRDS];

    /**
     * \brief   Reserved QDMA channels
     *
     * QDMA channels reserved during initialization for future use. These will
     * not be given when user requests for ANY available QDMA channel using
     * 'EDMA3_RM_QDMA_CHANNEL_ANY' as resource/channel id.
     */
    unsigned int        resvdQdmaChannels[EDMA3_MAX_QDMA_CHAN_DWRDS];

    /**
     * \brief   Reserved TCCs
     *
     * TCCs reserved during initialization for future use. These will not
     * be given when user requests for ANY available TCC using
     * 'EDMA3_RM_TCC_ANY' as resource/channel id.
     */
    unsigned int        resvdTccs[EDMA3_MAX_TCC_DWRDS];
}EDMA3_RM_InstanceInitConfig;



/**\struct      EDMA3_RM_Param
 * \brief       Used to Initialize the Resource Manager Instance
 *
 * This configuration structure is used to initialize the EDMA3 RM Instance.
 * This configuration information is passed while opening the RM instance.
 */
typedef struct {
    /** Shadow Region Identification */
    EDMA3_RM_RegionId               regionId;

    /**
     * It tells whether the EDMA3 RM instance is Master or not. Only the shadow
     * region associated with this master instance will receive the EDMA3
     * interrupts (if enabled).
     */
    unsigned short                  isMaster;

    /**
     * EDMA3 resources related shadow region specific information. Which all
     * EDMA3 resources are owned and reserved by this particular instance are
     * told in this configuration structure.
     * User can also pass this structure as NULL. In that case, default static
     * configuration would be taken from the platform specific configuration
     * files (part of the Resource Manager), if available.
     */
    EDMA3_RM_InstanceInitConfig     *rmInstInitConfig;

    /**
     * EDMA3 RM Instance specific semaphore handle.
     * Used to share resources (DMA/QDMA channels, PaRAM Sets, TCCs etc)
     * among different users.
     */
    void                            *rmSemHandle;

    /**
     * Whether initialization of Region Specific Registers is required or not?
     */
    unsigned short                  regionInitEnable;

    /** Instance wide Global Error callback parameters */
    EDMA3_RM_GblErrCallbackParams   gblerrCbParams;
} EDMA3_RM_Param;



/**\struct      EDMA3_RM_MiscParam
 * \brief       Used to specify the miscellaneous options during Resource
 * Manager Initialization.
 *
 * This configuration structure is used to specify some misc options
 * while creating the RM Object. New options may also be added into this
 * structure in future.
 */
typedef struct {
    /**
     * In a multi-master system (for e.g. ARM + DSP), this option is used to
     * distinguish between Master and Slave. Only the Master is allowed  to
     * program the global EDMA3 registers (like Queue priority, Queue water-
     * mark level, error registers etc).
     */
    unsigned short          isSlave;

    /** For future use **/
    unsigned short          param;
}EDMA3_RM_MiscParam;




/**\fn      EDMA3_RM_Result EDMA3_RM_create (unsigned int phyCtrllerInstId,
 *          const EDMA3_RM_GblConfigParams *gblCfgParams,
 *          const void *param)
 * \brief   Create EDMA3 Resource Manager Object
 *
 * This API is used to create the EDMA3 Resource Manager Object. It should be
 * called only ONCE for each EDMA3 hardware instance.
 *
 * Init-time Configuration structure for EDMA3 hardware is provided to pass the
 * SoC specific information. This configuration information could be provided
 * by the user at init-time. In case user doesn't provide it, this information
 * could be taken from the SoC specific configuration file
 * edma3_<SOC_NAME>_cfg.c, in case it is available.
 *
 * This API clears the error specific registers (EMCR/EMCRh, QEMCR, CCERRCLR)
 * and sets the TCs priorities and Event Queues' watermark levels, if the 'miscParam'
 * argument is NULL. User can avoid these registers' programming (in some specific
 * use cases) by SETTING the 'isSlave' field of 'EDMA3_RM_MiscParam' configuration
 * structure and passing this structure as the third argument (miscParam).
 *
 * After successful completion of this API, Resource Manager Object's state
 * changes to EDMA3_RM_CREATED from EDMA3_RM_DELETED.
 *
 * \param phyCtrllerInstId  [IN]    EDMA3 Controller Instance Id
 *                                 (Hardware instance id, starting from 0).
 * \param gblCfgParams      [IN]    SoC specific configuration structure for the
 *                                  EDMA3 Hardware.
 * \param miscParam         [IN]    Misc configuration options provided in the
 *                                  structure 'EDMA3_RM_MiscParam'.
 *                                  For default options, user can pass NULL
 *                                  in this argument.
 *
 * \return  EDMA3_RM_SOK or EDMA3_RM Error Code
 */
EDMA3_RM_Result EDMA3_RM_create (unsigned int phyCtrllerInstId,
                                const EDMA3_RM_GblConfigParams *gblCfgParams,
                                const void *miscParam);


/**\fn      EDMA3_RM_Result EDMA3_RM_delete (unsigned int phyCtrllerInstId,
 *                               const void *param)
 * \brief   Delete EDMA3 Resource Manager Object
 *
 * This API is used to delete the EDMA3 RM Object. It should be called
 * once for each EDMA3 hardware instance, ONLY after closing all the
 * previously opened EDMA3 RM Instances.
 *
 * After successful completion of this API, Resource Manager Object's state
 * changes to EDMA3_RM_DELETED.
 *
 * \param phyCtrllerInstId  [IN]    EDMA3 Phy Controller Instance Id (Hardware
 *                                  instance id, starting from 0).
 * \param   param           [IN]    For possible future use.
 *
 * \return  EDMA3_RM_SOK or EDMA3_RM Error Code
 */
EDMA3_RM_Result EDMA3_RM_delete (unsigned int phyCtrllerInstId,
                                const void *param);



/**\fn      EDMA3_RM_Handle EDMA3_RM_open (unsigned int phyCtrllerInstId,
 *                                const EDMA3_RM_Param *initParam,
 *                               EDMA3_RM_Result *errorCode)
 * \brief   Open EDMA3 Resource Manager Instance
 *
 * This API is used to open an EDMA3 Resource Manager Instance. It could be
 * called multiple times, for each possible EDMA3 shadow region. Maximum
 * EDMA3_MAX_RM_INSTANCES instances are allowed for each EDMA3 hardware
 * instance.
 *
 * Also, only ONE Master Resource Manager Instance is permitted. This master
 * instance (and hence the region to which it belongs) will only receive the
 * EDMA3 interrupts, if enabled.
 *
 * User could pass the instance specific configuration structure
 * (initParam->rmInstInitConfig) as a part of the 'initParam' structure,
 * during init-time. In case user doesn't provide it, this information could
 * be taken from the SoC specific configuration file edma3_<SOC_NAME>_cfg.c,
 * in case it is available.
 *
 * By default, this Resource Manager instance will clear the PaRAM Sets while
 * allocating them. To change the default behavior, user should use the IOCTL
 * interface appropriately.
 *
 * \param   phyCtrllerInstId    [IN]    EDMA3 Controller Instance Id (Hardware
 *                                      instance id, starting from 0).
 * \param   initParam           [IN]    Used to Initialize the Resource Manager
 *                                      Instance (Master or Slave).
 * \param   errorCode           [OUT]   Error code while opening RM instance.
 *
 * \return  Handle to the opened Resource Manager instance Or NULL in case of
 *          error.
 *
 * \note    This function disables the global interrupts (by calling API
 *          edma3OsProtectEntry with protection level
 *          EDMA3_OS_PROTECT_INTERRUPT) while modifying the global RM data
 *          structures, to make it re-entrant.
 */
EDMA3_RM_Handle EDMA3_RM_open (unsigned int phyCtrllerInstId,
                                const EDMA3_RM_Param *initParam,
                                EDMA3_RM_Result *errorCode);



/**\fn      EDMA3_RM_Result EDMA3_RM_close (EDMA3_RM_Handle hEdmaResMgr,
 *                                const void *param)
 * \brief  Close EDMA3 Resource Manager Instance
 *
 * This API is used to close a previously opened EDMA3 RM Instance.
 *
 * \param  hEdmaResMgr         [IN]    Handle to the previously opened Resource
 *                                     Manager Instance.
 * \param  param               [IN]    For possible future use.
 *
 * \return EDMA3_RM_SOK or EDMA3_RM Error Code
 *
 * \note    This function disables the global interrupts (by calling API
 *          edma3OsProtectEntry with protection level
 *          EDMA3_OS_PROTECT_INTERRUPT) while modifying the global RM data
 *          structures, to make it re-entrant.
 */
EDMA3_RM_Result EDMA3_RM_close (EDMA3_RM_Handle hEdmaResMgr,
                                const void *param);

/* @} Edma3RMBookkeep */




/**
 * \defgroup Edma3ResMgr EDMA3 Resources Management
 *
 * Resource Management part of the EDMA3 Resource Manager.
 *
 * @{
 */

/**\fn      EDMA3_RM_Result EDMA3_RM_allocResource (EDMA3_RM_Handle hEdmaResMgr,
 *                                        EDMA3_RM_ResDesc *resObj)
 * \brief   This API is used to allocate specified EDMA3 Resources like
 * DMA/QDMA channel, PaRAM Set or TCC.
 *
 * Note: To free the resources allocated by this API, user should call
 * EDMA3_RM_freeResource () ONLY to de-allocate all the allocated resources.
 *