mu_cdi.h

本程序为ST公司开发的源代码

/******************************************************************
*                                                                *
*        Copyright Mentor Graphics Corporation 2006              *
*                                                                *
*                All Rights Reserved.                            *
*                                                                *
*    THIS WORK CONTAINS TRADE SECRET AND PROPRIETARY INFORMATION *
*  WHICH IS THE PROPERTY OF MENTOR GRAPHICS CORPORATION OR ITS   *
*  LICENSORS AND IS SUBJECT TO LICENSE TERMS.                    *
*                                                                *
******************************************************************/

/*
 * MUSB-MicroSW USB Controller Driver Interface (UCDI).
 * $Revision: 1.6 $
 */

#ifndef __MUSB_CDI_H__
#define __MUSB_CDI_H__

#include "mu_tools.h"
#include "mu_dev.h"
#include "mu_stat.h"
#include "mu_dsi.h"

/************************* CDI CONSTANTS **************************/

/** Current UCDI version */
#define MUSB_CDI_REVISION	0x0100

/**
 * MUSB_PortType.
 * This is the type of USB port.
 */
typedef enum
{
    /** Unknown port type */
    MUSB_PORT_UNKNOWN,
    /** Function-only port */
    MUSB_PORT_TYPE_FUNCTION,
    /** Host-only port */
    MUSB_PORT_TYPE_HOST,
    /** OTG port */
    MUSB_PORT_TYPE_OTG
} MUSB_PortType;

/**
 * MUSB_PortSpeed.
 * This is the native speed of a USB port.
 */
typedef enum
{
    /** Unknown port speed */
    MUSB_PORT_SPEED_UNKNOWN,
    /** Low-speed USB */
    MUSB_PORT_SPEED_LOW,
    /** Full-speed USB */
    MUSB_PORT_SPEED_FULL,
    /** High-speed USB */
    MUSB_PORT_SPEED_HIGH
} MUSB_PortSpeed;

/**
 * MUSB_State.
 * The USB states passed to NewUsbState callback.
 */
typedef enum
{
    /** Powered off */
    MUSB_POWER_OFF,
    /** USB Powered state */
    MUSB_POWERED,
    /** USB Default state */
    MUSB_DEFAULT,
    /** USB Address state */
    MUSB_ADDRESS,
    /** USB Configured state */
    MUSB_CONFIGURED,
    /** Suspended (upon resume, the pre-suspend state will be signalled) */
    MUSB_SUSPENDED
} MUSB_State;

/**
 * MUSB_OtgState.
 * The USB/OTG states passed to NewOtgState callback.
 */
typedef enum
{
    /** OTG IDLE state */
    MUSB_AB_IDLE,
    /** OTG WAIT_VRISE state */
    MUSB_WAIT_VRISE,
    /** OTG B_PERIPHERAL state */
    MUSB_B_PERIPHERAL=0x11,
    /** OTG WAIT_ACON state */
    MUSB_B_WAIT_ACON,
    /** OTG B_HOST state */
    MUSB_B_HOST,
    /** OTG SRP_INIT state */
    MUSB_B_SRP_INIT,
    /** OTG A_PERIPHERAL state */
    MUSB_A_PERIPHERAL=0x21,
    /** OTG WAIT_BCON state */
    MUSB_A_WAIT_BCON,
    /** OTG A_HOST state */
    MUSB_A_HOST,
    /** OTG A_SUSPEND state */
    MUSB_A_SUSPEND,
    /** Special transitional state */
    MUSB_S_TRANSITION=0x30
} MUSB_OtgState;

/**
 * MUSB_ConnectionSpeed.
 * This is the speed of a USB connection.
 */
typedef enum
{
    /** Unknown connection speed */
    MUSB_CONNECTION_SPEED_UNKNOWN,
    /** Low-speed USB */
    MUSB_CONNECTION_SPEED_LOW,
    /** Full-speed USB */
    MUSB_CONNECTION_SPEED_FULL,
    /** High-speed USB */
    MUSB_CONNECTION_SPEED_HIGH
} MUSB_ConnectionSpeed;

/**
 * MUSB_TargetListCode.
 * The "opcodes" in target list.
 * A target list consists of a byte array, with these opcodes,
 * each followed by relevant data.
 * The order of items in the list is significant; the algorithm is first-match.
 * Examples:
 * <dl>
 * <dt>Simple VID/PID-based acceptance list:
 * <dd>MUSB_TARGET_VID, 0xab, 0x14, MUSB_TARGET_PID, 0x34, 0x12, MUSB_TARGET_ACCEPT, 0,<br>
 * MUSB_TARGET_VID, 0x5a, 0xa5, MUSB_TARGET_PID, 0x00, 0x05, MUSB_TARGET_ACCEPT, 1
 * <dt>Accept a communication device using Ethernet control model:
 * <dd>MUSB_TARGET_CLASS, 2, MUSB_TARGET_INTERFACE, 0, MUSB_TARGET_CLASS, 6, MUSB_TARGET_ACCEPT, 0
 * <dt>Accept all printers, regardless of VID/PID:
 * <dd>MUSB_TARGET_INTERFACE, 0, MUSB_TARGET_CLASS, 7, MUSB_TARGET_SUBCLASS, 1, MUSB_TARGET_ACCEPT, 2
 * <dt>Reject all printers with a uni-directional interface, but accept all other printers:
 * <dd>MUSB_TARGET_INTERFACE, 0, MUSB_TARGET_CLASS, 7, MUSB_TARGET_SUBCLASS, 1, MUSB_TARGET_PROTOCOL, 1, MUSB_TARGET_REJECT,<br>
 * MUSB_TARGET_INTERFACE, 0, MUSB_TARGET_CLASS, 7, MUSB_TARGET_SUBCLASS, 1, MUSB_TARGET_ACCEPT, 0
 * </dl>
 */
typedef enum
{
    /** 
     * Silently skipped; allows padding for cleaner-looking static declarations
     */
    MUSB_TARGET_UNKNOWN,
    
    /** Match a VID; followed by 2-byte VID (USB byte order) */
    MUSB_TARGET_VID,
    
    /** Match a PID; followed by 2-byte PID (USB byte order) */
    MUSB_TARGET_PID,
    
    /** 
     * Match a Device BCD code; 
     * followed by 2-byte Device BCD code (USB byte order)
     */
    MUSB_TARGET_DEVICE_BCD,
    
    /** 
     * Match the existence of a non-primary configuration and 
     * traverse to it; followed by 1-byte config index
     */
    MUSB_TARGET_CONFIG,
    
    /**
     * Match the existence of an interface and traverse to it; 
     * followed by 1-byte interface number
     */
    MUSB_TARGET_INTERFACE,
    
    /** 
     * Match a class at the current level (device or interface); 
     * followed by 1-byte class code
     */
    MUSB_TARGET_CLASS,
    
    /** 
     * Match a subclass at the current level (device or interface); 
     * followed by 1-byte subclass code
     */
    MUSB_TARGET_SUBCLASS,
    
    /** 
     * Match a protocol at the current level (device or interface); 
     * followed by 1-byte protocol code
     */
    MUSB_TARGET_PROTOCOL,
    
    /** 
     * Accept a target meeting previously-encountered criteria; 
     * followed by a 1-byte array index into the host client array.
     */
    MUSB_TARGET_ACCEPT,
    
    /** 
     * Reject a target meeting previously-encountered criteria; 
     * move on to next list item
     */
    MUSB_TARGET_REJECT
    
} MUSB_TargetListCode;

/*************************** CDI TYPES ****************************/

/**
 * MUSB_Port.
 * A USB receptacle (today, this maps one-to-one to an Inventra controller).
 *
 * @field bcdCdiRev filled with the version of the UCDI implemented by the port,
 * so client can check for compatibility
 *
 * @field Type the type of this port
 *
 * @field Speed the native speed of this port
 *
 * @field pPrivateData port-specific data; not to be interpreted by CDI client
 */
typedef struct 
{
    void* pPrivateData;
    uint16_t bcdCdiRev;
    MUSB_PortType Type;
    MUSB_PortSpeed Speed;
} MUSB_Port;

struct _MUSB_Device;
/**
 * MUSB_Device.
 * A device automatically addressed (but not configured)
 * by the UCD when the controller is in host mode.
 * Descriptors are left in USB byte order.
 * To get the value in a 16-bit field assuming you cast to the desired type, 
 * use MUSB_SWAP16P(&(pDescriptor->wShortField)).
 *
 * @field pPort the port on which the device is connected
 *
 * @field ConnectionSpeed connection speed
 * 
 * @field bBusAddress as per the USB standard; 1-127 are valid
 *
 * @field DeviceDescriptor as per the USB standard
 *
 * @field pCurrentConfiguration a device driver should 
 * set this to the apConfigDescriptors element in use.
 *
 * @field apConfigDescriptors as a convenience, an array of pointers to
 * configuration descriptors inside the descriptor buffer
 *
 * @field pDescriptorBuffer buffer of all "full" configuration descriptors
 * (that is, the set of descriptors associated with a configuration,
 * implied by the wTotalLength field of the configuration descriptor
 *
 * @field wDescriptorBufferLength the length (in bytes) of the descriptor buffer
 *
 * @field pPrivateData implementation data; not to be interpreted by UCDI clients
 * 
 * @field pDriverPrivateData driver instance data; not to be interpreted by UCD
 */
typedef struct _MUSB_Device
{
    MUSB_Port* pPort;
    void* pPrivateData;
    void* pDriverPrivateData;
    MUSB_DeviceDescriptor DeviceDescriptor;
    MUSB_ConfigurationDescriptor* pCurrentConfiguration;
    MUSB_ConfigurationDescriptor** apConfigDescriptors;
    uint8_t* pDescriptorBuffer;
    uint16_t wDescriptorBufferLength;
    MUSB_ConnectionSpeed ConnectionSpeed;
    uint8_t bBusAddress;
    struct _MUSB_Device* pParentUsbDevice;
    uint8_t bHubPort;
} MUSB_Device;

/** A handle to a port's bus */
typedef void* MUSB_BusHandle;

/**
 * MUSB_DeviceEndpoint.
 * Specification of a device-side endpoint for host use.
 *
 * @field UsbDescriptor the endpoint descriptor as per the USB standard
 *
 * @field pDevice associated device
 *
 * @field wNakLimit maximum number of NAK handshakes seen before
 * declaring an error (0xffff to disable NAK limit feature).
 * This works as per USB 2.0, so at full-speed it is the number of NAKs,
 * and at high-speed it is m, where the number of NAKs is 2^(m-1)
 */
typedef struct
{
    const MUSB_Device* pDevice;
    MUSB_EndpointDescriptor UsbDescriptor;
    uint16_t wNakLimit;
} MUSB_DeviceEndpoint;

/**
 * MUSB_EndpointResource.
 * A (local) resource for communicating with an endpoint.
 * A resource may be bound to a remote endpoint (e.g. Interrupt or Isochronous traffic),
 * and is always bound on the device side.
 * NOTE: members are not declared volatile; code will cast as necessary.
 *
 * @field dwBufferSize size (in bytes) of the underlying FIFO, ring buffer, etc.
 *
 * @field bmFlags flag bitmask (combination of MUSB_ENDPOINT_RESOURCE_FLAG_*)
 *
 * @field pPrivateData implementation data; not to be interpreted by CDI clients
 */
typedef struct
{
    uint32_t dwBufferSize;
    uint32_t bmFlags;
    void* pPrivateData;
} MUSB_EndpointResource;
/**
 * Flag denoting local resource is bound (not shared with other remote
 * endpoints [e.g. multiple bulk endpoints can share local resources])
 */
#define MUSB_ENDPOINT_RESOURCE_FLAG_BIND	(1 << 0)

/** Flag for DMA capability */
#define MUSB_ENDPOINT_RESOURCE_FLAG_DMA		(1 << 1)

/**
 * Pipe handle
 */
typedef void* MUSB_Pipe;

struct _MUSB_ControlIrp;

/**
 * Control IRP completion handler.
 * A completion handler for control transfers.
 * @param 1 pCompleteParam from IRP
 * @param 2 IRP pointer
 */
typedef void (*MUSB_pfControlIrpComplete)(void*, struct _MUSB_ControlIrp*);

/**
 * MUSB_ControlIrp.
 * IRP as per USB spec, for control transfers.
 * NOTE: members are not declared volatile; code will cast as necessary.
 *
 * @field pDevice pointer to target device
 *
 * @field pOutBuffer OUT data buffer, including the 8-byte standard request
 *
 * @field dwOutLength OUT data buffer length, in bytes
 *
 * @field pInBuffer IN data buffer
 *
 * @field dwInLength IN buffer length, in bytes
 *
 * @field dwStatus status on completion (updated before completion handler is called)
 *
 * @field dwActualOutLength actual OUT transfer length
 *
 * @field dwActualInLength actual IN transfer length
 *
 * @field pfIrpComplete required completion handler
 *
 * @field pCompleteParam passed to completion callback
 *
 * @field bAllowDma TRUE to allow DMA; FALSE otherwise
 */
typedef struct _MUSB_ControlIrp
{
    const MUSB_Device* pDevice;
    const uint8_t* pOutBuffer;
    uint32_t dwOutLength;
    uint8_t* pInBuffer;
    uint32_t dwInLength;
    uint32_t dwStatus;
    uint32_t dwActualOutLength;
    uint32_t dwActualInLength;
    MUSB_pfControlIrpComplete pfIrpComplete;
    void* pCompleteParam;
    uint8_t bAllowDma;
} MUSB_ControlIrp;

struct _MUSB_Irp;

/**
 * Bulk/Interrupt IRP completion handler.
 * A completion handler for bulk/interrupt transfers.
 * @param 1 pCompleteParam from IRP
 * @param 2 IRP pointer
 */
typedef void (*MUSB_pfIrpComplete)(void*, struct _MUSB_Irp*);

/**
 * MUSB_Irp (IRP for bulk/interrupt traffic).
 * IRP as per USB spec, for bulk/interrupt traffic.
 * NOTE: members are not declared volatile; code will cast as necessary.
 *
 * @field hPipe pipe handle, as returned by MUSB_OpenPipe or MUSB_Claim
 *
 * @field bAllowShortTransfer TRUE to treat a shorter-than-expected receive as successful,
 * or to transmit a null packet if the last packet is the endpoint's packet size
 *
 * @field pBuffer data buffer
 *
 * @field dwLength data buffer length, in bytes
 *
 * @field dwStatus status on completion (updated before completion handler is called)
 *
 * @field dwActualLength actual transfer length
 *
 * @field pfIrpComplete required completion handler
 *
 * @field pCompleteParam passed to completion callback
 *
 * @field bIsrCallback TRUE to issue callback in interrupt context;
 * FALSE to issue from background
 *
 * @field bAllowDma TRUE to allow DMA; FALSE otherwise
 */
typedef struct _MUSB_Irp
{
    MUSB_Pipe hPipe;