csl_bwmngmt.h

TI达芬奇dm644x各硬件模块测试代码

/*  ============================================================================
 *   Copyright (c) Texas Instruments Inc 2002, 2003, 2004, 2005
 *
 *   Use of this software is controlled by the terms and conditions found in the
 *   license agreement under which this software has been supplied.
 *   ===========================================================================
 */
/** @file csl_bwmngmt.h
 *
 *  @brief   Header file for functional layer of CSL
 *
 *  Description
 *    - The different enumerations, structure definitions
 *      and function declarations
 *
 *  PATH  \\(CSLPATH)\\ipmodules\\bwmngmt\\src
 *
 *  @date 28th May, 2004
 *  @author Chad Courtney
 */

/** @mainpage BWMNGMT Module
 *
 * @section Introduction
 *
 * @subsection xxx Purpose and Scope
 * The purpose of this document is to identify a set of common CSL APIs for
 * the BWMNGMT Module across various devices. The CSL developer
 * is expected to refer to this document while implementing APIs for these
 * modules . Some of the listed APIs may not be applicable to a given BWMNGMT
 *
 *
 *
 * @subsection aaa Terms and Abbreviations
 *   -# CSL     :  Chip Support Library
 *   -# API     :  Application Programmer Interface
 *   -# BWMNGMT :  Bandwidth Management Module
 *
 * @subsection References
 *    -# CSL 3.x Technical Requirements Specifications Version 0.5, dated
 *       May 14th, 2003
 *    -# Bandwidth Management Specification (Revision 0.22)
 *
 * @subsection Assumptions
 *     The abbreviations CSL, BWMNGMT have been used throughout this
 *     document to refer to the C64Plus Bandwidth Management Module.
 */

/* =============================================================================
 *  Revision History
 *  ===============
 *  11-Apr-2005 Brn updated the file for doxygen compatibiliy
 *
 * =============================================================================
 */

/**
@defgroup CSL_BWMNGMT_ENUM  Enumerated Data Types
@ingroup CSL_BWMNGMT_API
*/
/**
@defgroup CSL_BWMNGMT_API BWMNGMT
*/
/**
@defgroup CSL_BWMNGMT_DATASTRUCT  BWMNGMT Data Structures
@ingroup CSL_BWMNGMT_API
*/
/**
@defgroup CSL_BWMNGMT_SYMBOL  Symbols
@ingroup CSL_BWMNGMT_API
*/
/**
@defgroup CSL_BWMNGMT_FUNCTION  Functions
@ingroup CSL_BWMNGMT_API
*/

#ifndef _CSL_BWMNGMT_H_
#define _CSL_BWMNGMT_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <csl.h>
#include <cslr_bwmngmt.h>
#include <soc64plus.h>

/**@defgroup CSL_BWMNGMT_BLOCKSET_ENUM Control Block Set
*  @ingroup CSL_BWMNGMT_ENUM
@{*/
/** @brief Control Block Set for BWMNGMT
 *
 * This is used to indicate which control blocks (L1D, L2, and/or EXT) are to be
 * set within BWMNGMT for the given requestor (CPU, IDMA, SLAP, MAP, UC)
 * arbitration settings.
 */
typedef enum {
    /** All controller blocks will be update with given requestors arbitration
     *  setting
     */
    CSL_BWMNGMT_BLOCK_ALL = 7,
    /** L1D controller block will be update with given requestors arbitration
     *  setting
     */
    CSL_BWMNGMT_BLOCK_L1D = 1,
    /** L2 controller block will be update with given requestors arbitration
     *  setting
     */
    CSL_BWMNGMT_BLOCK_L2  = 2,
    /** EXT controller block will be update with given requestors arbitration
     *  setting
     */
    CSL_BWMNGMT_BLOCK_EXT = 4

}CSL_BwmngmtControlBlocks;
/**
@}*/

/**@defgroup CSL_BWMNGMT_ARBSETTINGS_ENUM Arbitration Settings
*  @ingroup CSL_BWMNGMT_ENUM
@{*/
/** @brief Priority Settings for BWMNGMT
 *
 * This is used to indicate to set the Priority arbitration settings for
 * the Requestors (CPU, IDMA, SLAP, MAP, UC)
 */
typedef enum {
    /** Priority arbitration setting 0 - Highest priority requestor */
    CSL_BWMNGMT_PRI_0 = CSL_BWMNGMT_CPUARBL1D_PRI_PRI0,
    /** Priority arbitration setting 1 - 2nd Highest priority requestor */
    CSL_BWMNGMT_PRI_1 = CSL_BWMNGMT_CPUARBL1D_PRI_PRI1,
    /** Priority arbitration setting 2 - 3rd Highest priority requestor */
    CSL_BWMNGMT_PRI_2 = CSL_BWMNGMT_CPUARBL1D_PRI_PRI2,
    /** Priority arbitration setting 3 - 4th Highest priority requestor */
    CSL_BWMNGMT_PRI_3 = CSL_BWMNGMT_CPUARBL1D_PRI_PRI3,
    /** Priority arbitration setting 4 - 5th Highest priority requestor */
    CSL_BWMNGMT_PRI_4 = CSL_BWMNGMT_CPUARBL1D_PRI_PRI4,
    /** Priority arbitration setting 5 - 6th Highest priority requestor */
    CSL_BWMNGMT_PRI_5 = CSL_BWMNGMT_CPUARBL1D_PRI_PRI5,
    /** Priority arbitration setting 6 - 7th Highest priority requestor */
    CSL_BWMNGMT_PRI_6 = CSL_BWMNGMT_CPUARBL1D_PRI_PRI6,
    /** Priority arbitration setting 7 - Lowest priority requestor */
    CSL_BWMNGMT_PRI_7 = CSL_BWMNGMT_CPUARBL1D_PRI_PRI7,
    /** Priority arbitration setting NULL - Due Not Program PRIORITY for this
     *  requestor
     */
    CSL_BWMNGMT_PRI_NULL = -1
}CSL_BwmngmtPriority;

/** @brief Maxwait Settings for BWMNGMT
 *
 * This is used to indicate to set Maxwait arbitration settings for
 * the Requestors (CPU, IDMA, SLAP, MAP, UC)
 */
typedef enum {
    /** Maxwait arbitration setting 0 - Always stall due to higher priority
     *  requestor
     */
    CSL_BWMNGMT_MAXWAIT_0 = CSL_BWMNGMT_CPUARBL1D_MAXWAIT_MAXWAIT0,
    /** Maxwait arbitration setting 1 - Stall max of 1 cycle due to higher
     *  priority requestor
     */
    CSL_BWMNGMT_MAXWAIT_1 = CSL_BWMNGMT_CPUARBL1D_MAXWAIT_MAXWAIT1,
    /** Maxwait arbitration setting 2 - Stall max of 2 cycle due to higher
     *  priority requestor
     */
    CSL_BWMNGMT_MAXWAIT_2 = CSL_BWMNGMT_CPUARBL1D_MAXWAIT_MAXWAIT2,
    /** Maxwait arbitration setting 4 - Stall max of 4 cycle due to higher
     *  priority requestor
     */
    CSL_BWMNGMT_MAXWAIT_4 = CSL_BWMNGMT_CPUARBL1D_MAXWAIT_MAXWAIT4,
    /** Maxwait arbitration setting 8 - Stall max of 8 cycle due to higher
     *  priority requestor
     */
    CSL_BWMNGMT_MAXWAIT_8 = CSL_BWMNGMT_CPUARBL1D_MAXWAIT_MAXWAIT8,
    /** Maxwait arbitration setting 16 - Stall max of 16 cycle due to higher
     *  priority requestor
     */
    CSL_BWMNGMT_MAXWAIT_16 = CSL_BWMNGMT_CPUARBL1D_MAXWAIT_MAXWAIT16,
    /** Maxwait arbitration setting 32 - Stall max of 32 cycle due to higher
     *  priority requestor
     */
    CSL_BWMNGMT_MAXWAIT_32 = CSL_BWMNGMT_CPUARBL1D_MAXWAIT_MAXWAIT32,
    /** Maxwait arbitration setting NULL - Due Not Program MAXWAIT for this
     *  requestor
     */
    CSL_BWMNGMT_MAXWAIT_NULL = -1
} CSL_BwmngmtMaxwait;

/** Enumaration for Hardware status query */
typedef enum
{
    PLACEHOLDER0 = 0
}CSL_BwmngmtHwStatusQuery;

/** Enumaration for Hardware control command */
typedef enum
{
    PLACEHOLDER2 = 0
}CSL_BwmngmtHwControlCmd;
/**
@}*/


/** @addtogroup CSL_BWMNGMT_DATASTRUCT
 *
 * @{ */
/** @brief CSL_BwmngmtHwSetup has all the fields required to configure BWMNGMT
 *
 * This structure has the substructures required to configure BWMNGMT at
 * Power-Up/Reset.
 *
 */
typedef struct CSL_BwmngmtHwSetup{
    /** CPU - Requestor Arbitration Settings - PRI                      */
    CSL_BwmngmtPriority         cpuPriority;
    /** CPU - Requestor Arbitration Settings - MAXWAIT                  */
    CSL_BwmngmtMaxwait          cpuMaxwait;
    /** IDMA (Internal DMA) Requestor Arbitration Settings - MAXWAIT    */
    CSL_BwmngmtMaxwait          idmaMaxwait;
    /** SLAP (Slave Port) Requestor Arbitration Settings - MAXWAIT      */
    CSL_BwmngmtMaxwait          slapMaxwait;
    /** MAP (Master Port) Requestor Arbitration Settings - PRI          */
    CSL_BwmngmtPriority         mapPriority;
    /** UC (User Coherence) Requestor Arbitration Settings - MAXWAIT    */
    CSL_BwmngmtMaxwait          ucMaxwait;
    /** Controller(s) to be set with Requestors Settings
     *  L1D, L2 and/or EXT
     */
    CSL_BwmngmtControlBlocks    control;
}CSL_BwmngmtHwSetup;

/**
@}
*/

/*
The following #define CSL_BWMNGMT_HWSETUP_DEFAULTS is meant to simplify the
implementation in C code by the customer.

CSL_BwmngmtHwSetup defaultSetup;
    defaultSetup.cpuPriority    = CSL_BWMNGMT_CPUARBL1D_PRI_RESETVAL;
    defaultSetup.cpuMaxwait     = CSL_BWMNGMT_CPUARBL1D_MAXWAIT_RESETVAL;
    defaultSetup.idmaMaxwait    = CSL_BWMNGMT_IDMAARBL2_MAXWAIT_RESETVAL;
    defaultSetup.slapMaxwait    = CSL_BWMNGMT_SLAPARBL1D_MAXWAIT_RESETVAL;
    defaultSetup.mapPriority    = CSL_BWMNGMT_MAPARBEXT_PRI_RESETVAL;
    defaultSetup.ucMaxwait      = CSL_BWMNGMT_UCARBL1D_MAXWAIT_RESETVAL;
    defaultSetup.control        = CSL_BWMNGMT_BLOCK_ALL;

*/

/* Default Setup Structure */
/**
 * The following #define CSL_BWMNGMT_HWSETUP_DEFAULTS is meant to simplify the
 * implementation in C code by the customer
 */
#define CSL_BWMNGMT_HWSETUP_DEFAULTS {  \
    (CSL_BwmngmtPriority)CSL_BWMNGMT_CPUARBL1D_PRI_RESETVAL, \
    (CSL_BwmngmtMaxwait)CSL_BWMNGMT_CPUARBL1D_MAXWAIT_RESETVAL,  \
    (CSL_BwmngmtMaxwait)CSL_BWMNGMT_IDMAARBL2_MAXWAIT_RESETVAL,  \
    (CSL_BwmngmtMaxwait)CSL_BWMNGMT_SLAPARBL1D_MAXWAIT_RESETVAL,  \
    (CSL_BwmngmtPriority)CSL_BWMNGMT_MAPARBEXT_PRI_RESETVAL,  \
    (CSL_BwmngmtMaxwait)CSL_BWMNGMT_UCARBL1D_MAXWAIT_RESETVAL,  \
    (CSL_BwmngmtControlBlocks)CSL_BWMNGMT_BLOCK_ALL  \
}

/**
@addtogroup CSL_BWMNGMT_DATASTRUCT
@{
*/
/** @brief This object contains the reference to the instance of BWMNGMT
 * opened using the @a CSL_BwmngmtOpen()
 *
 * The pointer to this is passed to all BWMNGMT CSL APIs.
 * This structure has the fields required to configure BWMNGMT for any test
 * case/application. It should be initialized as per requirements of a
 * test case/application and passed on to the setup function.
 */
typedef struct CSL_BwmngmtObj {
    /** This is a pointer to the registers of the instance of BWMNGMT
     * referred to by this object */
    CSL_BwmngmtRegsOvly    regs;
    /** This is the instance of BWMNGMT being referred to by this object */
    CSL_InstNum            bwmngmtNum;
}CSL_BwmngmtObj;
/**
@}
*/

/** @brief this is a pointer to @a CSL_BwmngmtObj & is passed as the first
 * parameter to all BWMNGMT CSL APIs
 */
typedef struct CSL_BwmngmtObj *CSL_BwmngmtHandle;

/** @brief this is a dummy object for the BWMNGMT parameters */
typedef void CSL_BwmngmtParam;

/** @brief this is a dummy object for the BWMNGMT Context */
typedef void CSL_BwmngmtContext;

/** ===========================================================================
 *   @n@b CSL_bwmngmtOpen
 *
 *   @b Description
 *        This function populates the peripheral data object for the instance
 *        and returns a handle to the instance.
 *        The open call sets up the data structures for the particular instance
 *        of BWMNGMT device. The device can be re-opened anytime after it has
 *        been normally closed if so required. BWMNGMT Hardware setup will be
 *        performed at the end of the open call only if the HwSetup Pointer
 *        supplied was non- NULL. The handle returned by this call is input as
 *        an essential argument for rest of the APIs described for this module.

 *
 *   @b Arguments
 *   @verbatim
 *
        pBwmngmtObj       Pointer to the BWMNGMT instance object

        bwmngmtNum        Instance of the BWMNGMT to be opened.

        pBwmngmtParam     Pointer to module specific parameters

        pStatus           pointer for returning status of the function call

 *   @endverbatim
 *
 *   <b> Return Value </b> CSL_BwmngmtHandle
 *        Valid BWMNGMT instance handle will be returned if status value is
 *        equal to CSL_SOK.
 *
 *   @b Example
 *   @verbatim
 *        CSL_status            status;
 *        CSL_BwmngmtObj        bwmngmtObj;
 *        CSL_BwmngmtHandle     hBwmngmt;
 *
 *        hBwmngmt = CSL_bwmngmtOpen (&bwmngmtObj,
 *                                   CSL_BWMNGMT_PER_CNT,
 *                                   NULL,
 *                                   &status
 *                                   );
 *  @endverbatim
 * ===========================================================================
 */
CSL_BwmngmtHandle  CSL_bwmngmtOpen
(
    /** Pointer to the handle object - to be allocated by the user
     */
    CSL_BwmngmtObj              *hBwmngmtObj,
    /** Specifies the instance of BWMNGMT to be opened */
    CSL_InstNum                 bwmngmtNum,
    /** Module specific parameters;
     *  Currently there are none; the user should pass 'NULL'
     */
    CSL_BwmngmtParam            *pBwmParam,
    /** Pointer to the variable that holds the holds the status of the open
     *  call
     */
    CSL_Status                  *status
);

/** ============================================================================
 *   @n@b CSL_bwmngmtClose
 *
 *   @b Description
 *   @n This function closes the specified instance of BWMNGMT.
 *
 *  <b> Usage Constraints: </b>
 *  Both @a CSL_bwmngmtInit() and @a CSL_bwmngmtOpen() must be called successfully
 *  in that order before @a CSL_bwmngmtClose() can be called.
 *
 *   @b Arguments
 *   @verbatim
         hBwmngmt           Handle to the BWMNGMT instance
 *    @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *                          CSL_SOK            - Close successful
 *                          CSL_ESYS_BADHANDLE - Invalid handle
 *
 *   @b Example
 *   @verbatim
 *     CSL_bwmngmtClose (hBwmngmt);
 *
 *  @endverbatim
 * =============================================================================
 */