csl_mbx.h

来自「dsp在音频处理中的运用」· C头文件 代码 · 共 387 行

/** ============================================================================
 *   @file  csl_mbx.h
 *
 *   @path  $(CSLPATH)\arm\mailbox\inc
 *
 *   @desc  Datatype definition header file for Mailbox CSL
 *
 */

 /* ============================================================================
 *   Copyright (c) Texas Instruments Inc 2002, 2003, 2004
 *
 *   Use of this software is controlled by the terms and conditions found in the
 *   license agreement under which this software has been supplied.
 *  ============================================================================
 */

/*  @(#) PSP/CSL 3.00.01.00[5912] (2004-04-28)  */

/* =============================================================================
 *  Revision History
 *  ===============
 *  24-Jun-2004 sp  Made modifications to support changes in CSL architecture
 *  25-May-2004 anj Added enum CSL_MbxHwControlCmd
 *                  Added CSL_MBX_QUERY_DATAREGS member to CSL_MbxHwStatusQuery
 *                  enum
 *                  Renamed the members of CSL_MbxNum enum
 *  28-Apr-2004 anj File Created.
 *
 * =============================================================================
 */

#ifndef _CSL_MBX_H_
#define _CSL_MBX_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <csl_error.h>
#include <csl_types.h>
#include <cslr_mbx.h>

/**
 *  Mailbox global typedef declarations
 */

/**
 *  Enumeration for mailbox data width
 */
typedef enum {
    /** 16-bit data width */
     CSL_MBX_DATA_16BIT              = 0,
    /** 32-bit data width */
     CSL_MBX_DATA_32BIT              = 1
} CSL_MbxDataWidth;

/**
 * Enumeration for mailbox control commands
 */
typedef enum {
    /** Write to the data registers (argusment type: CSL_MbxData * ) */
     CSL_MBX_CMD_WRITE_DATAREGS      = 0
} CSL_MbxHwControlCmd;

/**
 *  Enumeration for mailbox query commands
 */
typedef enum {
    /** Get the flag status (argument type: Bool ) */
     CSL_MBX_QUERY_FLAG_STATUS       = 0,
    /** Read from the data registers 
     *  (argument type: CSL_MbxData * ) 
     */
     CSL_MBX_QUERY_DATAREGS          = 1
} CSL_MbxHwStatusQuery;

/**
 *  Enumeration for mailbox access type
 */
typedef enum {
    /** Access type of the Mailbox as read only */
     CSL_MBX_RDONLY   = 1,
    /** Access type of the Mailbox as read and write */
     CSL_MBX_RDWR     = 2
} CSL_MbxAccessType;

/**
 *   Mailbox data
 */
typedef struct CSL_MbxData {
    /** Data width of the read/write operation on mailbox instance */
     CSL_MbxDataWidth        dataWidth;
    /** Pointer to data to be read/written from/to data registers of the 
     *   mailbox 
     */
    Uint32                   data;
} CSL_MbxData;

/**
 *   Mailbox data object
 */
typedef struct CSL_MbxObj {
    /** Pointer to the Data Register Overlay structure */
     CSL_MbxdataRegsOvly     dataRegs;
    /** Pointer to the Interrupt Register Overlay structure */
     CSL_MbxintrRegsOvly     intrRegs;
    /** Mailbox instance which is being requested */
     CSL_InstNum             perNum;
    /** Mailbox access type */
     CSL_MbxAccessType       accessType;
} CSL_MbxObj;

/**
 *   Pointer to the mailbox object structure
 */
typedef struct CSL_MbxObj *CSL_MbxHandle;

/** 
 *  This will have the base-address information for the peripheral
 *  instance
 */
typedef struct {
    /** Pointer to the data register overlay structure for mailbox */
     CSL_MbxdataRegsOvly    dataRegs;
    /** Pointer to the flag register overlay structure for mailbox */
     CSL_MbxintrRegsOvly    intrRegs;
} CSL_MbxBaseAddress;

/** 
 *  Module specific parameters.
 */
typedef struct{
    /** Access type of the Mailbox */
     CSL_MbxAccessType accessType;
} CSL_MbxParam;

/** 
 *  Module specific context information. Present implementation doesn't have
 *  any Context information.
 */
typedef struct {
    /** Context information of MBX.
     *  The below declaration is just a place-holder for future
     *  implementation.
     */
    Uint16 contextInfo;
} CSL_MbxContext;
                                                       
/**
 * Mailbox global function declarations
 */

/*
 * =============================================================================
 *   @func   CSL_mbxInit
 *
 *   @desc
 *      This is the peripheral specific intialization function. 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 touches
 *      the hardware.
 *
 *   @arg  pContext     Mailbox specific context information
 *
 *   @ret  CSL_Status
 *          CSL_SOK : Successful, desired operation is done.
 *
 *   @eg
 *      status = CSL_mbxInit(&mbxContext);
 *
 * =============================================================================
*/

CSL_Status CSL_mbxInit(
    CSL_MbxContext * pContext
    );

/*
 * =============================================================================
 *   @func   CSL_mbxOpen
 *
 *   @desc
 *      Opens the instance of MBX requested.
 *      The open call sets up the data structures for the particular instance 
 *      of MBX 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.
 *
 *   @arg  
 *          pMbxObj     Pointer to the object that holds reference to the 
 *                      instance of MBX requested after the call
 *   
 *          mbxNum      Instance of Mailbox to which a handle is requested
 * 
 *          pMbxParam   Pointer to the Mailbox param structure. Member of this 
 *                      structure specifies the access type of the mailbox
 * 
 *          pStatus     This returns the status (success/errors) of the call
 *
 *   @ret  CSL_Status
 *          CSL_SOK : Successful, desired operation is done.
 *          
 *   @eg
 *      status = CSL_mbxOpen(&mbxObj, CSL_MBX_ARM2DSP1, &mbxParam, &status);
 *
 * =============================================================================
*/

CSL_MbxHandle CSL_mbxOpen (
    CSL_MbxObj*         pMbxObj,
    CSL_InstNum         mbxNum,
    CSL_MbxParam        *pMbxParam,
    CSL_Status          *pStatus
 );

/*
 * =============================================================================
 *   @func   CSL_mbxClose
 *   @desc
 *     Close (Invalidate) mailbox instance (
 *     passed as handle) after it has finished
 *     operating. The instance cannot be accessed
 *     any more.
 *
 *   @arg  hMbx     Handle to mailbox instance
 *
 *   @ret  CSL_Status
 *          CSL_SOK : Successful, desired operation is done.
 *          CSL_ESYS_BADHANDLE : Handle pass is INVALID.
 *
 *   @eg
 *      status = CSL_mbxClose(hMbx);
 *
 * =============================================================================
*/

extern CSL_Status  CSL_mbxClose(
    CSL_MbxHandle      hMbx
);

/*
 * =============================================================================
 *   @func   CSL_mbxHwControl
 *
 *   @desc
 *     This function implements the control commands for mailbox.
 *     The only command supported is CSL_MBX_CMD_WRITE_DATAREGS.
 *     This command is used to write data into the data
 *     registers of a mailbox instance. Only instances
 *     CSL_MBX_ARM2DSP1 and CSL_MBX_ARM2DSP2 can be written
 *     using this function. There are two modes of writing
 *     data: 16-bit and 32-bit. In the 32-bit data mode, the
 *     data is written to both MPU2DSP1A/MPU2DSP2A and
 *     MPU2DSP1B/MPU2DSP2B.
 *
 *   @arg  
 *           hMbx        Handle to the mailbox instance
 *
 *           cmd        Command to be executed
 *   
 *           data       Data pointer corresponding to command
 *
 *   @ret  CSL_Status
 *         CSL_SOK               : Command execution successful
 *         CSL_ESYS_BADHANDLE    : Invalid instance handle
 *         CSL_ESYS_NOTSUPPORTED : Operation invalid on instance
 *         CSL_ESYS_INVCMD       : Invalid command
 *
 *   @eg
 *      status = CSL_mbxHwControl(hMbx, cmd, &cmdArg);
 *
 * =============================================================================
*/

extern CSL_Status  CSL_mbxHwControl(
    CSL_MbxHandle             hMbx,
    CSL_MbxHwControlCmd       cmd,
    void                      *cmdArg
);

/*
 * =============================================================================
 *   @func   CSL_mbxGetHwStatus
 *
 *   @desc
 *     Traces the various parameters of mailbox instance
 *     (passed as handle)
 *
 *     Usage Constraints:
 *     Instance should have been opened before with a valid
 *     handle.
 *
 *     The various operations that can be done are:
 *       1) Get the status flag
 *       2) Read the Mailbox registers
 *
 *       The function will return an error if cannot complete
 *       the request
 *
 *   @arg  
 *          hMbx        Handle to the mailbox instance
 *
 *          myQuery     The Values to be traced back
 *     
 *          response    This is a void pointer, and will be cast to
 *                      the required type.
 *
 *   @ret   CSL_Status
 *          CSL_OK              :  Query is successful
 *          CSL_ESYS_BADHANDLE  :  Invalid handle
 *          CSL_ESYS_INVQUERY   :  Invalid query
 *
 *   @eg
 *      CSL_mbxGetHwStatus(hmbx, myQuery, &response);
 *
 * =============================================================================
*/

extern CSL_Status  CSL_mbxGetHwStatus(
    CSL_MbxHandle            hMbx,
    CSL_MbxHwStatusQuery     myQuery,
    void                     *response
);

/**============================================================================
 *   @n@b CSL_mbxGetBaseAddress
 *
 *   @b Description
 *   @n This function returns the base-address of the
 *      specified MBX instance.
 *      Note: 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. Please refer 
 *          documentation for more details.
 *
 *   @b Arguments
     @verbatim
            mbxNum          Instance number
 
            pMbxParam       Pointer to the Mailbox param structure. Member of this 
                            structure specifies the access type of the mailbox
 
            pBaseAddress    Pointer to store the Base address details
     @endverbatim
 *
 *   <b> Return Value </b>  CSL_Status
 *   @li       CSL_SOK : Successful, desired operation is done.
 *   @li       CSL_ESYS_FAIL : Failure 
 *
 *   <b> Pre Condition </b>
 *   @n  None        
 *
 *   <b> Post Condition </b>
 *   @n         1. The base address details' structre is populated.
 *              2. The Mailbox access type information is populated in the
                    CSL_MbxParam structure.
 *
 *   @b Modifies
 *   @n  CSL_MbxParam structure  
 *
 *   @b Example
 *   @verbatim
            CSL_MbxParam        mbxParam;
            CSL_MbxBaseAddress  mbxBaseAddress;
            CSL_Status          status;
            
            status = CSL_mbxGetBaseAddress(CSL_MBX_ARM2DSP1, &mbxParam, &mbxBaseAddress);
     @endverbatim
 * ===========================================================================
 */

CSL_Status CSL_mbxGetBaseAddress(
    CSL_InstNum         mbxNum,
    CSL_MbxParam        *pMbxParam,
    CSL_MbxBaseAddress  *pBaseAddress
);


#ifdef __cplusplus
}
#endif

#endif  /* _CSL_MBX_H_ */