mu_cdi.h

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

    uint8_t* pBuffer;
    uint32_t dwLength;
    uint32_t dwStatus;
    uint32_t dwActualLength;
    MUSB_pfIrpComplete pfIrpComplete;
    void* pCompleteParam;
    uint8_t bAllowShortTransfer;
    uint8_t bIsrCallback;
    uint8_t bAllowDma;
} MUSB_Irp, MUSB_BulkIrp, MUSB_InterruptIrp;

struct _MUSB_IsochIrp;

/**
 * Isochronous IRP completion handler.
 * A completion handler for isochronous transfers.
 * @param 1 pCompleteParam from IRP
 * @param 2 IRP pointer
 */
typedef void (*MUSB_pfIsochIrpComplete)(void*, struct _MUSB_IsochIrp*);

/**
 * MUSB_IsochIrp (IRP for isochronous traffic).
 * IRP as per USB spec, for isochronous 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 wFrameCount the number of (micro)frames of data represented by this IRP
 *
 * @field pBuffer data buffer
 *
 * @field adwLength array of transfer lengths (in bytes), one per (micro)frame
 *
 * @field adwStatus array of storage for status codes, one per (micro)frame
 *
 * @field adwActualLength array of storage for actual transfer lengths, one per (micro)frame
 *
 * @field wCurrentFrame current (micro)frame, updated before calling callback
 * (but this should be considered volatile by completion handler)
 *
 * @field wCallbackInterval how often, in (micro)frames, to call the completion
 * handler before the IRP's last frame is reached
 * (0 to disable this feature)
 *
 * @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_IsochIrp
{
    MUSB_Pipe hPipe;
    uint8_t* pBuffer;
    uint32_t* adwLength;
    uint32_t* adwStatus;
    uint32_t* adwActualLength;
    MUSB_pfIsochIrpComplete pfIrpComplete;
    void* pCompleteParam;
    uint16_t wFrameCount;
    uint16_t wCurrentFrame;
    uint16_t wCallbackInterval;
    uint8_t bIsrCallback;
    uint8_t bAllowDma;
} MUSB_IsochIrp;

/**
 * USB state notification.
 * A callback to inform a client of a new USB state.
 * <p>
 * NOTE: this is called from interrupt context.
 * Its purpose is informational only; 
 * the callee is expected to do something low-overhead like updating state variables.
 * The callee should not call OS services unless they are interrupt-safe.
 *
 * @param 1 pPrivateData from the client's registration struct
 * @param 2 bus "handle"
 * @param 3 USB state
 */
typedef void (*MUSB_pfNewUsbState)(void*, MUSB_BusHandle, MUSB_State);

/**
 * SETUP servicing.
 * Requests a function client to service a control request from the host.
 * This is called only if the request cannot be fulfilled using
 * the client's provided descriptors.
 * <p>
 * NOTE: this is called from interrupt context.
 * The callee should not call OS services unless they are interrupt-safe.
 *
 * @param 1 pPrivateData from the client's registration struct
 * @param 2 bus "handle"
 * @param 3 unique sequence number for use in responding to this request
 * @param 3 request from host; 8-byte standard request plus any OUT data
 * @param 4 total length, in bytes, of request data
 *
 * @return TRUE on success (should have called MUSB_DeviceResponse)
 * @return FALSE to stall request (if it is known immediately that it is a bad request)
 * @see MUSB_DeviceResponse
 */
typedef uint8_t (*MUSB_pfDeviceRequest)(void*, MUSB_BusHandle, uint32_t,
	const uint8_t*, uint16_t);

/**
 * Device configuration callback.
 *
 * The UCD calls this when a SET_CONFIG() has been received from the host.
 * The callee is responsible for preparing suitable IRPs and starting transfers as applicable
 * (for example, an IRP should be submitted for each OUT endpoint, in anticipation of receiving
 * traffic from the host).
 * This call must complete in (500ms - UCD overhead), so a quick response is warranted.
 * For most devices, the IRPs and associated buffers may be declared statically,
 * so very little delay is expected.
 * <p>
 * NOTE: this is called from interrupt context.
 * The callee should not call OS services unless they are interrupt-safe.
 *
 * @param 1 pPrivateData from the client's registration struct
 * @param 2 bus "handle"
 * @param 3 bConfigurationValue config value; 0 => unconfigured, non-zero => configured
 * @param 4 array of pipe handles; one for each endpoint in the configuration,
 * in the same order as they appear in the descriptors.
 * Interfaces with alternate settings with different numbers of endpoints
 * will cause "holes" in this array when different alternates are selected.
 * For example, if interface 1's alt 0 has 2 endpoints but its alt 1 has 3,
 * the section of the array for interface 1 will always be 3 entries,
 * so the last of the 3 entries will be unused when alt 0 is selected.
 *
 * @return TRUE if configuration is acceptable and ready for traffic
 * @return FALSE to issue STALL handshake
 */
typedef uint8_t (*MUSB_pfDeviceConfigSelected)(void*, MUSB_BusHandle, uint8_t, MUSB_Pipe*);

/**
 * Interface set callback.
 *
 * The UCD calls this when a SET_INTERFACE() has been received from the host.
 * The callee is responsible for preparing suitable IRPs and starting transfers as applicable
 * (for example, an IRP should be submitted for each OUT endpoint, in anticipation of receiving
 * traffic from the host).
 * This call must complete in (500ms - UCD overhead), so a quick response is warranted.
 * For most devices, the IRPs and associated buffers may be declared statically,
 * so very little delay is expected.
 * <p>
 * NOTE: this is called from interrupt context.
 * The callee should not call OS services unless they are interrupt-safe.
 *
 * @param 1 pPrivateData from the client's registration struct
 * @param 2 bus "handle"
 * @param 3 bInterfaceNumber interface number from request
 * @param 4 bAlternateSetting alternate setting from request
 * @param 5 array of pipe handles; one for each endpoint in the configuration,
 * in the same order as they appear in the descriptors.
 * Interfaces with alternate settings with different numbers of endpoints
 * will cause "holes" in this array when different alternates are selected.
 * For example, if interface 1's alt 0 has 2 endpoints but its alt 1 has 3,
 * the section of the array for interface 1 will always be 3 entries,
 * so the last of the 3 entries will be unused when alt 0 is selected.
 *
 * @return TRUE if setting is acceptable and ready for traffic
 * @return FALSE to issue STALL handshake
 */
typedef uint8_t (*MUSB_pfInterfaceSet)(void*, MUSB_BusHandle, uint8_t, uint8_t, MUSB_Pipe*);

/**
 * MUSB_FunctionClient.
 * Registration information for a function client.
 *
 * @field pPrivateData client data; not to be interpreted by UCD
 * (but UCD passes it to client callbacks)
 *
 * @field wStringDescriptorCount the number of string descriptors per language,
 * if string descriptors are used.
 *
 * @field pStandardDescriptors a buffer of USB descriptors,
 * applicable for full or low speed, in USB byte order.
 * The suggested order is device, followed by strings if desired, 
 * and then each full configuration (config/interface/endpoint/etc.).
 * The positions of descriptors in the array imply their indexes as seen by the host.
 * String descriptors are organized like a two-dimensional array with
 * language ID as the major index.  So, for example, to support 2 string
 * descriptors for the two languages English (U.S.) and Hungarian,
 * the following order is required:
 * <ol>
 * <li>descriptor 0 (supported languages),
 * <li>descriptor 1 English, descriptor 2 English, 
 * <li>descriptor 1 Hungarian, descriptor 2 Hungarian.
 * </ol>
 * @field wDescriptorBufferLength the length, in bytes, 
 * of the descriptor buffer
 *
 * @field pbSelfPowered pointer to whether the client is self-powered;
 * the client may update this when not in a USB configured state
 *
 * @field pControlBuffer a buffer the UCD will use to store all incoming
 * control requests
 * @field wControlBufferLength size, in bytes, of control buffer
 *
 * @field pfDeviceRequest callback to service host SETUP requests
 *
 * @field pfDeviceConfigSelected callback for configuration
 *
 * @field pfInterfaceSet callback for interface setting
 * 
 * @field pfUsbState callback to notify client of relevant USB state changes
 * 
 * @field pHighSpeedDescriptors a buffer of USB descriptors,
 * applicable to high-speed operation, in USB byte order.
 * The expected content is device qualifier, followed by
 * each full configuration.
 * The UCD will use these descriptors and the ones in the
 * pStandardDescriptors to form an appropriate response to the host's
 * queries, depending on the actual negotiated bus speed.
 * 
 * @field wHighSpeedDescriptorLength the length, in bytes, 
 * of the high-speed descriptor buffer
 */
typedef struct
{
    void* pPrivateData;
    const uint8_t* pStandardDescriptors;
    uint16_t wDescriptorBufferLength;
    uint16_t wStringDescriptorCount;
    const uint8_t* pHighSpeedDescriptors;
    uint16_t wHighSpeedDescriptorLength;
    uint16_t wControlBufferLength;
    uint8_t* pControlBuffer;
    uint8_t* pbSelfPowered;
    MUSB_pfDeviceRequest pfDeviceRequest;
    MUSB_pfDeviceConfigSelected pfDeviceConfigSelected;
    MUSB_pfInterfaceSet pfInterfaceSet;
    MUSB_pfNewUsbState pfUsbState;
} MUSB_FunctionClient;

/**
 * Device connection notification.
 * Informs a host client of connection of a device (peripheral).
 *
 * @param 1 pPrivateData from the driver's registration struct
 * @param 2 bus "handle"
 * @param 3 pointer to device information
 * @param 4 pointer to the peripheral list entry which caused the
 * driver to be selected
 *
 * @return TRUE on success (device is tentatively accepted; may later call MUSB_RejectDevice)
 * @return FALSE if device is not supported (on OTG, relinquish host role if possible)
 */
typedef uint8_t (*MUSB_pfDeviceConnected)(void*, MUSB_BusHandle, MUSB_Device*,
	const uint8_t*);

/**
 * Device disconnection notification.
 * Informs a host client of disconnection of a device (peripheral).
 *
 * @param 1 pPrivateData from the driver's registration struct
 * @param 2 bus "handle"
 * @param 3 pointer to device information
 */
typedef void (*MUSB_pfDeviceDisconnected)(void*, MUSB_BusHandle, MUSB_Device*);

/**
 * Timer expiration callback.
 * This optional callback is called when an armed timer expires.
 * @param 1 pPrivateData from the driver's registration struct
 * @param 2 bus "handle"
 */
typedef void (*MUSB_pfDriverTimerExpired)(void*, MUSB_BusHandle);

/**
 * Bus suspension notification.
 * This optional callback is called when the bus is suspended.
 * @param 1 pPrivateData from the driver's registration struct
 * @param 2 bus "handle"
 */
typedef void (*MUSB_pfBusSuspended)(void*, MUSB_BusHandle);

/**
 * Bus resumption notification.
 * This optional callback is called when the bus is resumed.
 * @param 1 pPrivateData from the driver's registration struct
 * @param 2 bus "handle"
 */
typedef void (*MUSB_pfBusResumed)(void*, MUSB_BusHandle);

/**
 * MUSB_DeviceDriver (registration for a device driver).
 * Registration information for a device driver.
 *
 * @field pPrivateData client data; not to be interpreted by the UCD
 * (but the UCD passes it to client callbacks)
 *
 * @field bTimerCount how many millisecond-resolution timers this driver needs
 * 
 * @field adwTimerResolutions array of timer resolutions, one per timer
 * 
 * @field pfDeviceConnected callback for device connection notification
 *
 * @field pfDeviceDisconnected callback for device disconnection notification
 * 
 * @field pfBusSuspended if non-NULL, callback for bus suspension
 * 
 * @field pfBusResumed if non-NULL, callback for bus resumption
 */
typedef struct _MUSB_DeviceDriver
{
    void* pPrivateData;
    uint8_t bTimerCount;
    uint32_t* adwTimerResolutions;
    MUSB_pfDeviceConnected pfDeviceConnected;
    MUSB_pfDeviceDisconnected pfDeviceDisconnected;
    MUSB_pfBusSuspended pfBusSuspended;
    MUSB_pfBusResumed pfBusResumed;
} MUSB_DeviceDriver;

/**
 * MUSB_HostClient.
 * Registration information for a host client.
 * 
 * @field pPeripheralList array containing target list
 * (see MUSB_TargetListCode)
 * 
 * @field wPeripheralListLength byte count of peripheral list
 *
 * @field aDeviceDriverList by supplying an array of host clients,
 * the targeted peripheral list can be used as a driver selection mechanism.
 * 
 * @field bDeviceDriverListLength the number of elements in the device driver list
 */
typedef struct
{
    const uint8_t* pPeripheralList;
    uint16_t wPeripheralListLength;
    MUSB_DeviceDriver* aDeviceDriverList;
    uint8_t bDeviceDriverListLength;
} MUSB_HostClient;

/**
 * OTG state notification.
 * A callback to inform an OTG client of a new OTG state.
 *
 * @param 1 pPrivateData from the client's registration struct
 * @param 2 session "handle"
 * @param 3 OTG state
 */
typedef void (*MUSB_pfNewOtgState)(void*, MUSB_BusHandle, MUSB_OtgState);

/**
 * OTG error notification.
 * A callback to inform an OTG client of an OTG error.
 *
 * @param 1 pPrivateData from the client's registration struct
 * @param 2 session "handle"
 * @param 3 error code (MUSB_STATUS_OTG_NO_RESPONSE, MUSB_STATUS_UNSUPPORTED_DEVICE, 
 * MUSB_STATUS_UNSUPPORTED_HUB, or MUSB_STATUS_OTG_SRP_FAIL)
 */
typedef void (*MUSB_pfOtgError)(void*, MUSB_BusHandle, uint32_t);

/**
 * MUSB_OtgClient.
 * Registration information for an OTG client.
 *
 * @field pPrivateData client data; not to be interpreted by UCD
 * (but UCD passes it to client callbacks)
 *
 * @field pbDesireHostRole pointer to whether the role of host is desired 
 * at the next possible opportunity.  
 * This applies to the B-device only (it will have no effect on the A-device).
 *
 * @field pfOtgState callback to notify client of OTG state changes
 *
 * @field pfOtgError callback to notify client of OTG errors
 */
typedef struct
{
    void* pPrivateData;
    uint8_t* pbDesireHostRole;
    MUSB_pfNewOtgState pfOtgState;
    MUSB_pfOtgError pfOtgError;
} MUSB_OtgClient;

/**
 * Callback for enumeration completion on a hub port
 * @param pHubUsbDevice USB device representation of Hub. 
 * The new device is connected to this hub.
 * @param pChildUsbDevice Pointer to new USB device enumerated by UCD. 
 */
typedef void (*MUSB_pfHubEnumerationComplete)(
    MUSB_Device *pHubUsbDevice, 
    MUSB_Device *pChildUsbDevice
    );

/************************* CDI FUNCTIONS **************************/

#if 0
/**
 * Count available ports.
 * Discover the number of ports available.
 * @return the number of available ports
 */
extern uint16_t MUSB_CountPorts(void);

#endif /*0*/

/**
 * Get a port.
 * @param wPortIndex the index (counting from 0) of the desired port
 * @return port pointer on success; NULL on failure
 */
extern MUSB_Port* MUSB_GetPort(uint16_t wPortIndex);

/**
 * Register a function client.
 * Typically, a function client is registered once, at "boot" time.
 *
 * @param pPort the port, which must be of Type==MUSB_PORT_TYPE_FUNCTION
 *
 * @param pFunctionClient provides the necessary information for the UCD
 * to implement standard requests, and callbacks for 
 * the UCD to notify the client of required events
 *
 * @return a non-NULL bus "handle" on success
 */
extern MUSB_BusHandle MUSB_RegisterFunctionClient(
    MUSB_Port* pPort,
    MUSB_FunctionClient* pFunctionClient
    );