csl_bwmngmt.h

Dm6455 driver,magbe useful to you!

/* ============================================================================
 * 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
 * provided
 * ============================================================================
 */
 
/** =========================================================================== 
 * @file csl_bwmngmt.h
 *
 * @brief Header file for functional layer of CSL
 *
 * @path $(CSLPATH)\bwmngmt\src
 * 
 * Description
 *    - The different enumerations, structure definitions
 *      and function declaration
 *
 *  @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
 *
 *  16-Nov-2005 ds  updated the documentation
 * =============================================================================
 */

#ifndef _CSL_BWMNGMT_H_
#define _CSL_BWMNGMT_H_

#ifdef __cplusplus
extern "C" {
#endif

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

    

/** 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;


/** @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;


/** @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 {
    /** 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  \
           }


/**
 * This will have the base-address information for the peripheral instance
 */
typedef struct {
    /** Base-address of the Configuration registers of BWMNGMT */
    CSL_BwmngmtRegsOvly regs;
} CSL_BwmngmtBaseAddress;

/**
 *  BWMNGMT specific parameters. Present implementation doesn't have
 *  any specific parameters.
 */
typedef struct {
    /** Bit mask to be used for module specific parameters.
     *  The below declaration is just a place-holder for future
     *  implementation.
     */
    CSL_BitMask16   flags;
} CSL_BwmngmtParam;

/**
 *  BWMNGMT specific context information. Present implementation doesn't
 *  have any Context information.
 */
typedef struct {
    /** Context information of BWMNGMT.
     *  The below declaration is just a place-holder for future
     *  implementation.
     */
    Uint16  contextInfo;
} CSL_BwmngmtContext;

/** @brief This object contains the reference to the instance of BWMNGMT
 *  opened using the @a CSL_bwmngmtOpen(). The pointer to this object is passed 
 *  as BWMNGMT handle to all BWMNGMT CSL APIs. . CSL_bwmngmtOpen() function 
 *  initializes this structure based on the parameters passed. 
 */
typedef struct {
    /** 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 CSL_BwmngmtObj *CSL_BwmngmtHandle;

/** ===========================================================================
 *  @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> Pre Condition </b>
 *  @n  The CSL system as well as BWMNGMT must be succesfully initialized
 *      via @a CSL_sysInit() and @a CSL_bwmngmtInit() before calling this
 *      function. Memory for the @a CSL_BwmngmtObj must be allocated outside
 *      this call. This object must be retained while usage of this peripheral.
 *
 *  <b> Post Condition </b>
 *  @n  None
 *
 *  @b  Modifies
 *  @n  None
 *
 *  @b Example
 *  @verbatim
        CSL_status            status;
        CSL_BwmngmtObj        bwmngmtObj;
        CSL_BwmngmtHandle     hBwmngmt;
        
        ...
        hBwmngmt = CSL_bwmngmtOpen(&bwmngmtObj, CSL_BWMNGMT_0, 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_bwmngmtOpen
 *
 *   @b Description
 *        This function populates the peripheral data object for the instance
 *        and returns a handle to the BWMNGMT 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.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> Pre Condition </b>
 *   @n  The BWMNGMT module must be successfully initialized via 
 *       CSL_bwmngmtInit() before calling this function. 
 *
 *   <b> Post Condition </b>
 *   @n  1. The status is returned in the status variable. If status returned is 
 *			CSL_SOK - Valid BWMNGMT handle is returned. 
 *			CSL_ESYS_FAIL - The BWMNGMT instance is invalid. 
 *   	 2. BWMNGMT object structure is populated.