csl_bwmngmt.h

Dm6455 driver,magbe useful to you!

 *
 *
 *   @b  Modifies
 *   @n  1. The status variable 
 *		 2. BWMNGMT object structure 
 *
 *  @b Example
 *  @verbatim
        ...
        CSL_bwmngmtClose(hBwmngmt);
        ...
    @endverbatim
 * ============================================================================
 */
CSL_Status CSL_bwmngmtClose (
    /* Pointer to the object that holds reference to the
     * instance of BWMNGMT requested after the call 
     */
    CSL_BwmngmtHandle hBwmngmt
);


/*  ============================================================================
 *  @n@b CSL_bwmngmtHwSetup
 *
 *   @b Description
 *   @n Configures the BWMNGMT using the values passed in through the
 *      setup structure.
 *
 *   @b Arguments
 *   @verbatim

         hBwmngmt            Handle to the BWMNGMT instance

         setup               Setup structure for BWMNGMT

     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *                          CSL_SOK            - Close successful
 *                          CSL_ESYS_BADHANDLE - Invalid handle
 *                          CSL_ESYS_INVPARAMS - If setup is NULL
 *
 *   <b> Pre Condition </b>
 *   @n  Both @a CSL_bwmngmtInit() and @a CSL_bwmngmtOpen() must be called
 *       successfully in that order before this function can be called. The
 *       main setup structure consists of fields used for the configuration at
 *       start up. The user must allocate space for it and fill in the main
 *       setup structure fields appropriately before a call to this function
 *       is made. \n
 *
 *   <b> Post Condition </b>
 *   @n  BWMNGMT registers are configured according to the hardware setup 
 *       parameters
 *
 *   @b  Modifies
 *   @n  The following registers and fields are programmed by this API \n
 *   1.  CPU Arbitration Parameters \n
 *       -   PRI field set in L1D, L2 and/or EXT \n
 *       -   MAXWAIT field set in L1D, L2 and/or EXT \n
 *
 *   2.  IDMA Arbitration Parameter \n
 *       -   MAXWAIT field set in L1D, L2 and/or EXT \n
 *
 *   3.  SLAP Arbitration Parameter \n
 *       -   MAXWAIT field set in L1D, L2 and/or EXT \n
 *
 *   4.  MAP Arbitration Parameter \n
 *       -   PRI field set in EXT \n
 *
 *   5.  UC Arbitration Parameter \n
 *       -   MAXWAIT field set in L1D and/or L2 \n
 *
 *  The @b control: bitmask indicates which of the three control blocks
 *  (L1D, L2 and EXT) will be set with the associated PRI and MAXWAIT values 
 *  Note: That if associated control block is not programmable for given 
 *  requestor then it will not ignored but no error will be provide.  This 
 *  allows the user to set control to CSL_BWMNGMT_BLOCK_ALL which is the 
 *  default value. This will set all programmed arbitration values for a given 
 *  requestor to the same value across \n the blocks which is recommended.
 *  If PRI is set to CSL_BWMNGMT_PRI_NULL (-1) then no change will be made 
 *  for the corresponding requestors priority level.
 *  If MAXWAIT is set to CSL_BWMNGMT_MAXWAIT_NULL (-1) then no change will be 
 *  made for the corresponding requestors maxwait setting.

 *  @b Examples:
 *  @verbatim

    Example 1: Sets Priorities and Maxwaits to default values

        CSL_BwmngmtHandle hBwmngmt;
        CSL_BwmngmtHwSetup hwSetup;
        hwSetup = CSL_BWMNGMT_HWSETUP_DEFAULTS;
        ...

        // Init Successfully done
        ...
        // Open Successfully done
        ...
        CSL_bwmngmtHwSetup(hBwmngmt, &hwSetup);


    Example 2: Sets CPU Priority to 1, CPU Maxwait to 8, MAP Priority to 6 for 
    all blocks (L1D, L2 and EXT)

        CSL_BwmngmtHandle hBwmngmt;
        CSL_BwmngmtHwSetup hwSetup;
        hwSetup.cpuPriority = CSL_BWMNGMT_PRI_1;
        hwSetup.cpuMaxwait  = CSL_BWMNGMT_MAXWAIT_8;
        hwSetup.idmaMaxwait = CSL_BWMNGMT_MAXWAIT_NULL;
        hwSetup.slapMaxwait = CSL_BWMNGMT_MAXWAIT_NULL;
        hwSetup.mapPriority = CSL_BWMNGMT_PRI_6;
        hwSetup.ucMaxwait   = CSL_BWMNGMT_MAXWAIT_NULL;
        hwSetup.control     = CSL_BWMNGMT_BLOCK_ALL;
        ...

        // Init Successfully done
        ...
        // Open Successfully done
        ...
        CSL_bwmngmtHwSetup(hBwmngmt, &hwSetup);
     @endverbatim
 *
 *  ===========================================================================
 */
CSL_Status CSL_bwmngmtHwSetup (
    /* Pointer to the object that holds reference to the
     * instance of BWMNGMT requested after the call
     */
    CSL_BwmngmtHandle  hBwmngmt,
    
    /* Pointer to setup structure which contains the
     * information to program BWMNGMT to a useful state
     */
    CSL_BwmngmtHwSetup *setup
);


/*  ============================================================================
 *  @n@b CSL_bwmngmtGetHwSetup
 *
 *   @b Description
 *   @n Gets the current set up of BWMNGMT
 *
 *  @b Arguments
 *  @verbatim
          hBwmngmt            Handle to the BWMNGMT instance

          setup               Setup structure for BWMNGMT

      @endverbatim
 *
 *  <b> Return Value </b>  CSL_Status
 *  					   CSL_SOK            - Close successful
 *  					   CSL_ESYS_BADHANDLE - Invalid handle
 *  					   CSL_ESYS_INVPARAMS - IF setup is NULL
 *
 *  <b> Pre Condition </b>
 *  @n Both CSL_bwmngmtInit() and CSL_bwmngmtOpen() must be called
 *     successfully in that order before this function can be called.
 *
 *   <b> Post Condition </b>
 *   @n  None
 *
 *   @b  Modifies
 *   @n 
 *   1.  CPU Arbitration Parameters 
 *       -   PRI field set in Control Block Specified by "control" \n
 *       -   MAXWAIT field set in Control Block Specified by "control"  \n
 *
 *   2.  IDMA Arbitration Parameter \n
 *       -   MAXWAIT field set in Control Block Specified by "control"  \n
 *
 *   3.  SLAP Arbitration Parameter \n
 *       -   MAXWAIT field set in Control Block Specified by "control"  \n
 *
 *   4.  MAP Arbitration Parameter \n
 *       -   PRI field set in Control Block Specified by "control"  \n
 *       if not EXT then returns CSL_BWMNGMT_PRI_NULL \n
 *
 *   5.  UC Arbitration Parameter \n
 *       -   MAXWAIT field set in Control Block Specified by "control" \n
 *       if not L1D or L2 then returns CSL_BWMNGMT_MAXWAIT_NULL \n
 *
 *  @b Example:
 *  @verbatim

        CSL_BwmngmtHandle hBwmngmt;
        CSL_BwmngmtHwSetup hwSetup;
        hwSetup.control = CSL_BWMNGMT_BLOCK_L1D;
        // only CSL_BWMNGMT_BLOCK_L1D, CSL_BWMNGMT_BLOCK_L2, or
        // CSL_BWMNGMT_BLOCK_EXT are valid
        ...

        // Init Successfully done
        ...
        // Open Successfully done
        ...
        CSL_bwmngmtGetHwSetup(hBwmngmt, &hwSetup);

    @endverbatim
 *  ===========================================================================
 */
CSL_Status CSL_bwmngmtGetHwSetup (
    /* Pointer to the object that holds reference to the
     * instance of BWMNGMT requested after the call
     */
    CSL_BwmngmtHandle  hBwmngmt,

    /* Placeholder to return the status; @a CSL_BwmngmtHwSetup* */
    CSL_BwmngmtHwSetup *mySetup
);


/*  ============================================================================
 *  @n@b CSL_bwmngmtHwControl
 *
 *  @b Description
 *  @n Takes a command of BWMNGMT with an optional argument & implements it.
 *     Not Implemented. For future use
 *
 *  @b Arguments
 *  @verbatim
           hBwmngmt        Handle to the BWMNGMT instance

           cmd             The command to this API indicates the action to be
                            taken on BWMNGMT.

           arg             An optional argument.

    @endverbatim
 *
 *  <b> Return Value </b>  CSL_Status
 *  @li         CSL_SOK               - Control info return successful.
 *  @li         CSL_ESYS_BADHANDLE    - Invalid handle
 *  @li         CSL_ESYS_INVCMD       - Invalid command
 *
 *  <b> Pre Condition </b>
 *   @n  None
 *
 *  <b> Post Condition </b>
 *  @n  None
 *
 *  @b Modifies
 *  @n The hardware registers of BWMNGMT.
 *
 *  @b Example
 *  @verbatim
        CSL_BwmngmtHandle         hBwmngmt;
        CSL_BwmngmtHwControlCmd   cmd;
        void                      arg;
        
        ...
        status = CSL_bwmngmtHwControl (hBwmngmt, cmd, &arg);
        ...
     @endverbatim
 * =============================================================================
 */
CSL_Status CSL_bwmngmtHwControl (
    /* Pointer to the object that holds reference to the
     * instance of BWMNGMT requested after the call
     */
    CSL_BwmngmtHandle       hBwmngmt,
    
    /* The command to this API which indicates the action to be taken */
    CSL_BwmngmtHwControlCmd cmd,
    
    /* Optional argument @a void* casted */
    void                    *cmdArg
);


/*  ============================================================================
 *   @n@b CSL_bwmngmtInit
 *
 *   @b Description
 *   @n This is the initialization function for the BWMNGMT. This function must
 *      be called before calling any other API from this CSL.This function is
 *		idem-potent. Currently, the function just returns status CSL_SOK, 
 *      without doing anything.
 *
 *   @b Arguments
     @verbatim
            pContext   Context information for the instance. Should be NULL
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK - Always returns
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  None
 *
 *   @b Modifies
 *   @n  None
 *
 *   @b Example
 *   @verbatim
       ...
          CSL_bwmngmtInit();
     @endverbatim
 *  ===========================================================================
 */
CSL_Status CSL_bwmngmtInit (
    /* BWMNGMT Context */
    CSL_BwmngmtContext *pContext
);


/*  ============================================================================
 *  @n@b CSL_bwmngmtGetHwStatus
 *
 *  @b Description
 *  @n Gets the status of the different operations of BWMNGMT. Not Implemented.
 *     For future use
 *
 *  @b Arguments
 *  @verbatim
           hBwmngmt      Handle to the BWMNGMT instance

           query         The query to this API of BWMNGMT which indicates the
                         status to be returned.

           response      Placeholder to return the status.
    @endverbatim
 *
 *  <b> Return Value </b>  CSL_Status
 *  @li                    CSL_SOK             - Status info return successful
 *  @li         			CSL_ESYS_INVQUERY   - Invalid query
 *
 *  <b> Pre Condition </b>
 *  @n  None
 *
 *  <b> Post Condition </b>
 *  @n  None
 *
 *  @b Modifies
 *  @n None
 *
 *  @b Example
 *  @verbatim
       CSL_BwmngmtHandle          hBwmngmt;
       CSL_BwmngmtHwStatusQuery   query;
       void                       reponse;
       
       ...
       status = CSL_GetbwmngmtHwStatus(hBwmngmt, query, &response);
       ...
     @endverbatim
 * =============================================================================
 */
CSL_Status CSL_bwmngmtGetHwStatus (
    /* Pointer to the object that holds reference to the
     * instance of BWMNGMT requested after the call
     */
    CSL_BwmngmtHandle        hBwmngmt,
    
    /* The query to this API which indicates the status/setup
     * to be returned
     */
    CSL_BwmngmtHwStatusQuery myQuery,
    
    /* Placeholder to return the status; @a void* casted */
    void                     *response
);

/** ============================================================================
 *   @n@b CSL_bwmngmtGetBaseAddress
 *
 *   @b Description
 *   @n  Function to get the base address of the peripheral instance.
 *       This function is used for getting the base address of the peripheral
 *       instance. This function will be called inside the CSL_bwmngmtOpen()
 *       function call. This function is open for re-implementing if the user
 *       wants to modify the base address of the peripheral object to point to
 *       a different location and there by allow CSL initiated write/reads into
 *       peripheral. MMR's go to an alternate location.
 *
 *   @b Arguments
 *   @verbatim
            bwmngmtNum        Specifies the instance of the bwmngmt to be opened.

            pBwmngmtParam     Module specific parameters.

            pBaseAddress      Pointer to baseaddress structure containing base
                              address details.

     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_OK            Successful on getting the base 
 *                                            address of bwmngmt
 *   @li                    CSL_ESYS_FAIL     The instance number is invalid.
 *
 *   <b> Pre Condition </b>
 *   @n  None
 *
 *   <b> Post Condition </b>
 *   @n  Base Address structure is populated
 *
 *   @b Modifies
 *   @n    1. The status variable
 *
 *         2. Base address structure is modified.
 *
 *   @b Example
 *   @verbatim
        CSL_Status              status;
        CSL_BwmngmtBaseAddress  baseAddress;

       ...
      status = CSL_bwmngmtGetBaseAddress(CSL_BWMNGMT, NULL, &baseAddress);

     @endverbatim
 * ===========================================================================
 */

#ifdef __cplusplus
}
#endif

#endif