csl_memprot.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.             
 *   ===========================================================================
 */ 
/** @mainpage Memory Protection CSL 3.x
 *
 * @section Introduction
 *
 * @subsection xxx Purpose and Scope
 * The purpose of this document is to describe the common API's and data
 * structures for the Memory Protection module.
 *
 * @subsection aaa Terms and Abbreviations
 *   -# CSL:  Chip Support Library
 *   -# API:  Application Programmer Interface
 *
 * @subsection References
 *    -# CSL-001-DES, CSL 3.x Design Specification DocumentVersion 1.02
 *
 */

/** @file csl_memprot.h
 *
 * @path $(CSLPATH)\\memprot\\src
 *
 * @brief    Header file for functional layer of CSL
 *
 * Description
 *    - The different enumerations, structure definitions
 *      and function declarations
 *
 * Modification 1
 *    - modified on: 06/23/2004
 *    - reason: Created the sources
 *
 * @date 23rd Jun, 2004
 * @author Ruchika Kharwar
 *
 */
#ifndef _CSL_MEMPROT_H_
#define _CSL_MEMPROT_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <csl.h>
#include <cslr_memprot_L2.h>
#include <cslr_memprot_L1D.h>
#include <cslr_memprot_L1P.h>
#include <cslr_memprot_config.h>
#include <soc64plus.h>
/**
@defgroup CSL_MEMPROT_API MEMPROT
*/
/**
@defgroup CSL_MEMPROT_DATASTRUCT  MEMPROT Data Structures
@ingroup CSL_MEMPROT_API
*/
/**
@defgroup CSL_MEMPROT_SYMBOL  MEMPROT Symbols Defined
@ingroup CSL_MEMPROT_API
*/
/**
@defgroup CSL_MEMPROT_ENUM  MEMPROT Enumerated Data Types
@ingroup CSL_MEMPROT_API
*/

/**
@defgroup CSL_MEMPROT_FUNCTION  MEMPROT Functions
@ingroup CSL_MEMPROT_API
*/
/**
@defgroup CSL_MEMPROT_FUNCTION_INTERNAL  MEMPROT Internal Functions
@ingroup CSL_MEMPROT_FUNCTION
*/

/**
@addtogroup CSL_MEMPROT_SYMBOL
@{
*/
/**************************************************************************\
* Memory Protection global macro declarations. These are used to setup the
* Memory protection attribute pages. The relevant symbols can also be used
* when after querying the fault status with the errorMask.
*
\**************************************************************************/

#define CSL_MEMPROT_MEMACCESS_UX              0x0001
 /**< User Execute permission           */
#define CSL_MEMPROT_MEMACCESS_UW              0x0002
/**< User Write permission              */
#define CSL_MEMPROT_MEMACCESS_UR              0x0004
/**< User Read permission               */
#define CSL_MEMPROT_MEMACCESS_SX              0x0008
/**< Supervisor Execute permission */
#define CSL_MEMPROT_MEMACCESS_SW              0x0010
/**< Supervisor Write permission */
#define CSL_MEMPROT_MEMACCESS_SR              0x0020
/**< Supervisor Read permission */
#define CSL_MEMPROT_MEMACCESS_EMU             0x0040
/**< Emulation security permission */
#define CSL_MEMPROT_MEMACCESS_NS              0x0080
/**< Secure Access permission */
#define CSL_MEMPROT_MEMACCESS_LOCAL           0x0100
/**< Local Access */
#define CSL_MEMPROT_MEMACCESS_EXT             0x0200
/**< External Allowed ID. VBus  requests with PrivID >= '6' are
     permitted if access type is allowed*/
#define CSL_MEMPROT_MEMACCESS_AID0            0x0400
/**< Allowed ID '0' */
#define CSL_MEMPROT_MEMACCESS_AID1            0x0800
/**< Allowed ID '1' */
#define CSL_MEMPROT_MEMACCESS_AID2            0x1000
/**< Allowed ID '2' */
#define CSL_MEMPROT_MEMACCESS_AID3            0x2000
/**< Allowed ID '3' */
#define CSL_MEMPROT_MEMACCESS_AID4            0x4000
/**< Allowed ID '4' */
#define CSL_MEMPROT_MEMACCESS_AID5            0x8000
/**< Allowed ID '5' */
/**
@}
*/

/** Constants for passing parameters to the functions.
 */

/** @addtogroup CSL_MEMPROT_DATASTRUCT
* @{ */
/** @brief Pointer to the L2 memeory protection overlay registers */
typedef volatile CSL_Memprotl2RegsOvly CSL_MemprotRegsOvly;

/** @brief This object contains the reference to the instance of memory
 *  Protection Module opened using the @a CSL_memprotOpen().
 *
 *  A pointer to this object is passed to all Memory Protection CSL APIs.
 */

typedef struct CSL_MemprotObj {
    /** This is a pointer to the memory protection registers of the module
        for which memory protection is requested.
     */
    CSL_MemprotRegsOvly regs;
    /** This is the instance of module number i.e L2/L1D/L1P/CONFIG */
    CSL_InstNum         modNum;
} CSL_MemprotObj;

/** @brief MEMPROT handle.
*/
typedef struct CSL_MemprotObj *CSL_MemprotHandle;

/** @brief Dummy structure */
typedef void CSL_MemprotParam;

/** @brief Dummy structure */
typedef void CSL_MemprotConfig;

/** @brief This is the setup structure used with the HwSetup API
 */
typedef struct {
    /** This should point to a table of memory page attributes*/
    Uint16* memPageAttr;
    /** This should point to an array of 2 32 bit elements
        (constituting the key) */
    Uint32* key;
    /** This is the number of pages which need to be programmed
        starting from 0 */
    Uint16  numPages;
}CSL_MemprotHwSetup;
/** @brief This will have the base-address information for the module
 *  instance
 */
typedef struct {
    /** Base-address of the memory protection registers
     */
    CSL_MemprotRegsOvly regs;
} CSL_MemprotBaseAddress;

/** @brief Module specific context information. Present implementation
 *  doesn't have any Context information.
 */

typedef struct {
    /** Context information of Memory Protection.
     *  The below declaration is just a place-holder for future
     *  implementation.
     */
    Uint16  contextInfo;
} CSL_MemprotContext;
/** @brief This will be used to query the memory fault status.
 */
typedef struct {
    Uint32           addr;             /**< Memory Protection Fault Address */
    CSL_BitMask16    errorMask;        /**< Bit Mask of the Errors */
    Uint16           fid;              /**< Faulted ID */
}CSL_MemprotFaultStatus;

/** @brief This will be used to set/query the memory page attributes
 */

typedef struct {
    CSL_BitMask16    attr;           /**< Memory Protection Page attributes */
    Uint16           page;           /**< Memory Protection Page number */
}CSL_MemprotPageAttr;

/**
@}
*/
/** @addtogroup CSL_MEMPROT_ENUM
* @{ */
/** @brief Enumeration for queries passed to @a CSL_memprotGetHwStatus()
 *
 *  This is used to get the status of different operations or he current
 *  register settings.
 */
typedef enum {
  /** Gets the fault status from the unit
    (response type:@a CSL_MemprotFaultStatus *) */
  CSL_MEMPROT_QUERY_FAULT,
  /** Get the memory protection page attributes
    (response type: @a CSL_MemprotPageAttr *) */
  CSL_MEMPROT_QUERY_PAGEATTR,
  /** Memory protection Lock status
    (response type: @a CSL_MemprotLockStatus *) */
  CSL_MEMPROT_QUERY_LOCKSTAT
} CSL_MemprotHwStatusQuery;


/** @brief Enumeration for commands passed to @a CSL_memprotHwControl()
 *
 * This is used to select the commands to control the operations in the Module
 */
typedef enum {
    /** Locks the Memory Protecion Unit (command argument
        @a Uint32* (An array of 2 32 bits elements constituing the key)) */
    CSL_MEMPROT_CMD_LOCK,
    /** Unlocks the Memory Protecion Unit (command argument
        @a Uint32* (An array of 2 32 bits elements constituing the key)) */
    CSL_MEMPROT_CMD_UNLOCK,
    /** Sets the page attributes (command argument @a CSL_MemprotPageAttr*) */
    CSL_MEMPROT_CMD_PAGEATTR
} CSL_MemprotHwControlCmd;

/** @brief Enumeration for queried lock status.
 */
typedef enum {
    /** Non secure Lock */
    CSL_MEMPROT_LOCKSTAT_NSLOCK   = 1,
    /** Secure Lock */
    CSL_MEMPROT_LOCKSTAT_SLOCK    = 3,
    /** Non secure UnLock */
    CSL_MEMPROT_LOCKSTAT_NSUNLOCK = 0,
    /** Secure UnLock */
    CSL_MEMPROT_LOCKSTAT_SUNLOCK  = 2
} CSL_MemprotLockStatus;
/**
@}
*/
/**************************************************************************\
* Memory Protection global function declarations
\**************************************************************************/
/** @addtogroup CSL_MEMPROT_FUNCTION
* @{ */
/** ===========================================================================
 *   @n@b CSL_memprotInit
 *
 *   @b Description
 *   @n This is the initialization function for the MEMPROT. This function is
 *      idempotent in that calling it many times is same as calling it once.
 *      This function initializes the CSL data structures, and doesn't affect
 *      the H/W.
 *
 *   @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>
 *       This function should be called before using any of the CSL APIs
 *       in the Memory Protection module.
 *
 *       Note: As Memory Protection doesn't have any context based information,
 *       the function  just returns CSL_SOK. User is expected to pass NULL.
 *
 *   <b> Post Condition </b>
 *   @n  None
 *
 *   @b Modifies
 *   @n  None
 *
 *   @b Example
 *   @verbatim
      ...
      if (CSL_sysInit() == CSL_SOK) {
         CSL_memprotInit();
      }
     @endverbatim
 * ============================================================================
 */
CSL_Status CSL_memprotInit(
    /** module specific context information
     */
    CSL_MemprotContext * pContext
    );


/** ===========================================================================
 *   @n@b CSL_memprotOpen
 *
 *   @b Description
 *   @n 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 MEMPROT device.The device can be re-opened anytime after it has been
 *      normally closed if so required.MEMPROT 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
              pMemprotObj     Pointer to the MEMPROT instance object

              memprotNum      Instance of the MEMPROT to be opened

              pMemprotParam   Pointer to module specific parameters

              pStatus         pointer for returning status of the function call
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_MemprotHandle
 *   @n                     Valid MEMPROT instance handle will be returned if
                            status value is equal to CSL_SOK.
 *
 *   <b> Pre Condition </b>
 *  Memory protection must be successfully initialized via @a CSL_memprotInit()
 *  before calling this function. Memory for the @a CSL_MemoprotObj must be
 *  allocated outside this call. This object must be retained while usage of
 *  this module.Depending on the module opened some inherant constraints need
 *  to be kept in mind. When a handle for the Config block is opened the only
 *  operation  possible is a query for the fault Status. No other control
 *  command/ query/ setup must be used.
 *  When a handle for L1D/L1P is opened then too constraints wrt the number of
 *  Memory pages must be kept in mind.
 *
 *   <b> Post Condition </b>
 *   @n   1.    MEMPROT object structure is populated
 *   @n   2.    The status is returned in the status variable. If status
 *              returned is
 *   @li            CSL_SOK             Valid ata handle is returned
 *   @li            CSL_ESYS_FAIL       The ata instance is invalid
 *   @li            CSL_ESYS_INVPARAMS  Invalid parameter
 *
 *   @b Modifies
 *   @n    1. The status variable
 *   @n    2. MEMPROT object structure
 *
 *   @b Example
 *  @verbatim

            CSL_MemprotObj mpL2Obj;
            CSL_MemprotHandle hmpL2;
            CSL_Status status;
            // Initializing the module
            CSL_memprotInit(NULL);

            // Opening the Handle for the L2
            hmpL2 = CSL_memprotOpen(&mpL2Obj,
                                  CSL_MEMPROT_L2,
                                  NULL,
                                  &status);
   @endverbatim
 * ============================================================================
 */
CSL_MemprotHandle CSL_memprotOpen (
    /** Pointer to the object that holds reference to the
     *  instance of memory protection unit requested after the call
     */
    CSL_MemprotObj*          pMemprotObj,
    /** Instance of memory protection unit to which a handle is requested
     */
    CSL_InstNum              memNum,
    /** Module specific parameters;
     * Currently there are none; the user should pass 'NULL'
     */
    CSL_MemprotParam        *pMemParam,
    /** This returns the status (success/errors) of the call.
     * Could be 'NULL' if the user does not want status information.
     */
    CSL_Status              *pStatus
);


/** ===========================================================================
 *   @n@b CSL_memprotClose
 *
 *   @b Description
 *   @n This function closes the specified instance of MEMPROT.
 *
 *   @b Arguments
 *   @verbatim
            hAta            Handle to the MEMPROT instance
     @endverbatim
 *
 *   <b> Usage Constraints: </b>
 *   CSL_memprotInit(), CSL_memprotOpen() must be opened prior to this call.
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li                    CSL_SOK             - Close successful
 *   @li                    CSL_ESYS_BADHANDLE  - Invalid handle
 *
 *   @b Example
 *   @verbatim
             CSL_MemprotHandle hMem;
            CSL_status          status;

            ...