csl_usbhc.h

来自「dsp在音频处理中的运用」· C头文件 代码 · 共 1,496 行 · 第 1/4 页

	CSL_UsbhcRegsOvly regs;
	/** This is the instance of USBHC being referred to by this object  */
	CSL_InstNum  	perNum;
} CSL_UsbhcObj;

typedef struct CSL_UsbhcObj *CSL_UsbhcHandle;

/** @brief This will have the base-address information for the peripheral
 *  instance
 */
typedef struct {
	/** Base-address of the Configuration registers of the peripheral
	 */
	CSL_UsbhcRegsOvly	regs;
} CSL_UsbhcBaseAddress;


/** @brief Module specific parameters. Present implementation doesn't have
 *  any module 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_UsbhcParam;

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

typedef struct {
	/** Context information of USBHC.
         *  The below declaration is just a place-holder for future
 	 *  implementation.
 	 */
    Uint16	contextInfo;
} CSL_UsbhcContext;

/** @brief Opens the instance of USBHC requested.
 *
 *  The open call sets up the data structures for the particular instance of
 *  USBHC 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> Usage Constraints: </b>
 *  USBHC must be successfully initialized via @a CSL_usbhcInit() before calling
 *  this function. Memory for the @a CSL_usbhcObj must be allocated outside
 *  this call. This object must be retained while usage of this peripheral.
 *
 *  @b Example:
 *  @verbatim

	  CSL_UsbhcObj     usbhcObj;
	  CSL_Status       status;
 		...
	  hUsbhc = CSL_usbhcOpen(&usbhcObj,
                          CSL_USBHC_1,
                          NULL,
                          &status);
   @endverbatim
 *
 * @return returns a handle @a CSL_UsbhcHandle to the requested instance of
 * USBHC if the call is successful, otherwise, a @a NULL is returned.
 *
 */
CSL_UsbhcHandle CSL_usbhcOpen (
    /** Pointer to the object that holds reference to the
     *  instance of USBHC requested after the call
     */
    CSL_UsbhcObj*		    pUsbhcObj,
    /** Instance of USBHC to which a handle is requested
     */
    CSL_InstNum              usbhcNum,
    /** Module specific parameters;
     * Currently there are none; the user should pass 'NULL'
     */
    CSL_UsbhcParam          *pUsbhcParam,
    /** This returns the status (success/errors) of the call.
     * Could be 'NULL' if the user does not want status information.
     */
    CSL_Status              *pStatus
	);
/**
@defgroup CSL_USBHC_CLOSE_API USB Host Close API
@ingroup CSL_USBHC_API
@brief Closes the instance of USBHC requested
@{*/
CSL_Status  CSL_usbhcClose
(
    /** Pointer to the object that holds reference to the
     * instance of USBHC requested after the call */
	CSL_UsbhcHandle           hUsbhc
);
/**
@}*/
/**
@defgroup CSL_USBHC_SETUP_API USB Host Setup API
@ingroup CSL_USBHC_API
@brief Programs the USBHC with the setup configuration as specified in the 
       arguments
@{*/
CSL_Status  CSL_usbhcHwSetup
(
	/** Pointer to the object that holds reference to the
     * instance of USBHC requested after the call */
	CSL_UsbhcHandle           hUsbhc,
	/** Pointer to setup structure which contains the
     * information to program USBHC to a useful state */
	CSL_UsbhcHwSetup*         setup
);
/**
@}*/
/**
@defgroup CSL_USBHC_CONTROL_API USB Host Control API
@ingroup CSL_USBHC_API
@brief Controls the different operations that can be performed by USBHC
@{*/

CSL_Status  CSL_usbhcHwControl
(
	/** Pointer to the object that holds reference to the
     * instance of USBHC requested after the call */
	CSL_UsbhcHandle           hUsbhc,
	/** The command to this API which indicates the action to be taken */
	CSL_UsbhcHwControlCmd     cmd,
	/** Optional argument @a void* casted */
	void                     *cmdArg
);

/** @brief Peripheral specific initialization function.
 *
 * 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.
 *
 * <b> Usage Constraints: </b>
 * This function should be called before using any of the CSL APIs in the USBHC
 * module.
 *
 *  Note: As USBHC doesn't have any context based information, currently, the 
 *  function just returns CSL_SOK. User is expected to pass NULL in the
 *  function call.
 *
 * @b Example:
 * @verbatim

   ...
   if (CSL_SOK != CSL_usbhcInit(NULL)) {
       return;
   }
   @endverbatim
 *
 * @return returns the status of the operation
 *
 */

CSL_Status CSL_usbhcInit(
	/** USBHC specific context information
	 */
	CSL_UsbhcContext * pContext
	);
/**
@}*/
/**
@defgroup CSL_USBHC_QUERY_API USB Host Query API
@ingroup CSL_USBHC_API
@brief Returns the status of the requested operation/parameter of USBHC
@{*/
CSL_Status  CSL_usbhcGetHwStatus
(
	/** Pointer to the object that holds reference to the
     * instance of USBHC requested after the call */
	CSL_UsbhcHandle           hUsbhc,
	/** The query to this API which indicates the status/setup
     * to be returned */
	CSL_UsbhcHwStatusQuery    myQuery,
	/** Placeholder to return the status; @a void* casted */
	void                     *response
);
/**
@}*/
/**
@defgroup CSL_USBHC_GETSETUP_API USB Host Query Setup API
@ingroup CSL_USBHC_API
@brief Queries the USBHC setup
@{*/
CSL_Status  CSL_usbhcGetHwSetup
(
	/** Pointer to the object that holds reference to the
     * instance of USBHC requested after the call */
	CSL_UsbhcHandle           hUsbhc,
	/** Pointer to setup structure which is filled in by the API call */
	CSL_UsbhcHwSetup*         setup
);
/**
@}*/

/**
@defgroup CSL_USBHC_SAMPLE USB Host CSL Usage Description
@ingroup CSL_USBHC_API
@{
<b>Typical Usage Scenario</b>

This section attempts to put down the typical fit of the USB Host CSL in a 
driver/application/user codebase.

<b>Initialization</b>

1. The driver identifies the control parameters associated with the Controller.
   This includes the Root Hub A,B parameters.

2. A call is made to the CSL_open(..)  API which returns a handle to the Host 
   Controller, however no change is made to the operating state of the Host 
   Controller, hence the controller may not yet be sending any SOF's on the bus.

3. When the system wants to start using the Host Controller the driver must 
   identify control-bulk ratio, interrupts to  be enabled, lists to be 
   enabled, low speed threshold, addresses of the Shared RAM and addresses 
   in the Shared RAM area for the control and Bulk lists. After the above 
   identification the driver must issue the START command. Beyond this SOF's 
   are generated on the bus.


<b>Addition and Removal of Endpoint Descriptors</b>

1.The driver must allocate memory for an Endpoint Descriptor data structure 
  from the Shared RAM, initialize the fields in the Endpoint as per the OHCI 
  specification and link into the appropriate list by modifying the approppriate 
  Control/Bulk list Head Register or the correct Interrupt Head table index. 
  While updating the list the CSL_USBHC_CMD_LIST_DISABLE/ENABLE commands might 
  be required to be used.

2.The driver must identify the endpoint descriptor to be removed when it needs 
  to close the pipe (at the time of device disconnect/change of configuration 
  of the device), traverse the appropriate physical list and removed.
  In order to reclaim the memory from the Shared RAM, the driver must make 
  certain the endpoint is no longer in use by the Host Controller. This is 
  done by disabling the list in question, and ensuring the Current
  ED does not point to the Endpoint attempting removal.


<b>Addition and Removal of Transfer Requests</b>

1.New transfer Descriptors are always added to the tail of the tail of the 
  transfer queue. The driver must allocate memory for a new transfer 
  descriptor in the Shared RAM.

2.The driver must identify the Endpoint descriptor to which the transfer 
  descriptor needs to be linked to and update the Endpoint Descriptor
  along with the Transfer Descriptor Tail TD.


<b>Typical Interrupt Service Routine</b>

This is an extremely bare skeleton and there has little relevance to 
actual implementation. \n\n
  interrupt void USBHC_isr {\n
  Uint32 interruptSource;\n
  CSL_usbhcGetHwStatus(pHchandle,CSL_USBHC_QUERY_INTREVENTS,&interruptSource);\n
  if (interruptSource & CSL_USBHC_EVENT_OWNERSHIP_CHG)\n
  {\n
    .. // Use the registered Callback function for the Ownership Change \n
  }\n
  if (interruptSource &CSL_USBHC_EVENT_ROOTHUBSTATUS_CHG)\n
  {\n
    .. // Will happen when a new device is connected to the controller \n
    .. // Invoke the registered Call back function to start to the driver that 
          inturn starts the enumeration 		\n
       // process for the device  \n
  }\n
  if (interruptSource & CSL_USBHC_EVENT_UNRECOVERERROR )\n
  {\n
    .. // Invoke the registered Host Recovery callback function  \n
  }\n
  if (interruptSource & CSL_USBHC_EVENT_WRITEDONEHEAD)\n
  {\n
    ..// Invoke the registered Done  callback function. This function checks the
          Completion code in the \n
      //   Done transfer descriptor and takes appropriate action        \n
  }\n
}  \n
@}
*/

/** @brief 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_usbhcOpen()
 *  function call.
 *
 *  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 the documentation for
 *        more details.
 *
 * @b Example:
 * @verbatim

      CSL_Status status;
      CSL_UsbhcBaseAddress   baseAddress;

       ...
      status = CSL_usbhcGetBaseAddress(CSL_UART_1, NULL, &baseAddress);
   @endverbatim
 *
 * @return Returns the status of the operation (see @a CSL_Status)
 *
 */

CSL_Status CSL_usbhcGetBaseAddress(
        /** Instance number
         */
        CSL_InstNum  		usbhcNum,
        /** Module specific parameters
         */
        CSL_UsbhcParam *		pUsbhcParam,
        /** Base address details
         */
        CSL_UsbhcBaseAddress *	pBaseAddress
);


/** @brief Function to configure the USBHC registers.
 *
 *  This funciton is used to configure the USB Host Controller, in raw mode.
 *  The 'config' parameter specifies the register values, which are loaded
 *  into the USBHC registers. The USBHC should be opened, using CSL_usbhcOpen()
 *  before calling this function.
 *
 * @b Example:
 * @verbatim

	CSL_Status status;
	CSL_UsbhcConfig config;

	...
	config->HCCONTROL = xxxx;
	config->HCCOMMANDSTATUS = xxxx;

	...
	status = CSL_usbhcHwSetupRaw(hUsbhc, &config);
   @endverbatim
 *
 *
 * @return Returns CSL_SOK
 *
 */
CSL_Status  CSL_usbhcHwSetupRaw (
    /** Pointer to the object that holds reference to the
     *  instance of usbhc to be configured
	 */
    CSL_UsbhcHandle         hUsbhc,
    /** Pointer to setup structure which contains the
     *  information to program USBHC to a useful state
	 */
    CSL_UsbhcConfig *     config
);

#ifdef __cplusplus
}
#endif

#endif