mu_cdi.h

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

/**
 * Register a host client, powering up the USB.
 *
 * @param pPort the port, which must be of Type==MUSB_PORT_TYPE_HOST
 *
 * @param pHostClient provides the necessary information for the UCD
 * to determine supported devices, and the callbacks for the UCD
 * to notify each device driver of required events
 *
 * @return a non-NULL bus "handle" on success
 */
extern MUSB_BusHandle MUSB_RegisterHostClient(
    MUSB_Port* pPort,
    MUSB_HostClient* pHostClient
    );

/**
 * Register an OTG client.
 * If the underlying port is the A-device, this will power-up the USB,
 * and the host role is initially assumed.
 * If the underlying port is the B-device, this will connect to the USB,
 * and the function role is initially assumed.
 * Under client control, such a session may be relinquished
 * to another host-capable OTG device, or the bus may be suspended
 * to save power.
 *
 * @param pPort the port, which must be of Type==MUSB_PORT_TYPE_OTG
 *
 * @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
 *
 * @param pHostClient provides the necessary information for the UCD
 * to determine supported devices, and the callbacks for the UCD
 * to notify each device driver of required events
 *
 * @param pOtgClient provides the necessary information for the UCD
 * to implement required behavior, and callbacks for 
 * the UCD to notify the client of required events
 *
 * @return a non-NULL bus "handle" on success
 */
extern MUSB_BusHandle MUSB_RegisterOtgClient(
    MUSB_Port* pPort,
    MUSB_FunctionClient* pFunctionClient,
    MUSB_HostClient* pHostClient,
    MUSB_OtgClient* pOtgClient
    );

#if 0
/**
 * Get current (micro)frame.
 * Get the current (micro)frame number on a bus.
 * @param hBus the bus "handle"
 * @return the current (micro)frame number
 */
extern uint32_t MUSB_GetBusFrame(MUSB_BusHandle hBus);

/**
 * Deactivate a client.
 * Attempts to deactivate the currently-registered client.
 * If it is a host client or host-role OTG client,
 * the bus will be suspended.
 * If it is a function client or function-role OTG client,
 * the controller will disconnect from the USB if supported.
 * After a successful call, the given handle is no longer valid
 * for use in other calls.
 * @param hBus the bus "handle"
 * @return TRUE on success
 * @return FALSE if the operation is not possible (soft-disconnect not supported)
 */
extern uint8_t MUSB_DeactivateClient(MUSB_BusHandle hBus);

/**
 * Request use of the bus.
 * If the current OTG state allows this transition,
 * the bus will be requested.
 * If this is the A-device, the session will be started
 * and default to host.
 * If this is the B-device, SRP will be initiated.
 * @param hBus the bus "handle"
 * @return TRUE on success
 * @return FALSE if the operation is not possible (wrong OTG state)
 */
extern uint8_t MUSB_RequestBus(MUSB_BusHandle hBus);

#endif /*0*/

/**
 * Suspend the bus (host and OTG only).
 * @param hBus the bus "handle"
 */
extern void MUSB_SuspendBus(MUSB_BusHandle hBus);

#if 0
/**
 * Resume the bus.
 * @param hBus the bus "handle"
 */
extern void MUSB_ResumeBus(MUSB_BusHandle hBus);

#endif /*0*/

/**
 * Relinquish host role (OTG only).
 * For OTG, relinquish the host role to another.
 * The mechanism for reporting the status of this operation is the client's
 * pfOtgState callback.
 * @param hBus the bus "handle"
 */
extern void MUSB_RelinquishHost(MUSB_BusHandle hBus);

#if 0
/**
 * (Advanced) Control parsing of control requests from the host.
 * By default, control requests from the host are parsed,
 * so that most standard requests are handled by the stack,
 * leaving a function client creator to code class- or vendor-specific parsing.
 * In rare cases, the automatic parser needs to be disabled for a time
 * (for example, to implement the transport phase of the Device Firmware Upgrade class).
 * @param hBus the bus "handle"
 * @param bParse TRUE to enable the stack's parser; FALSE to disable it.
 * While parsing is disabled, the function client will receive ALL control OUT data.
 */
extern void MUSB_SetFunctionParse(MUSB_BusHandle hBus, uint8_t bParse);

#endif /*0*/

/**
 * (Advanced) Bind to an endpoint as function.
 * Most clients will not need this function, since appropriate pipes are 
 * automatically opened and passed in the ConfigSelected/InterfaceSet callbacks.
 * However, if a function does not use the USB device framework mechanism
 * to describe its endpoints, it can use this call to open a pipe for a given endpoint.
 * It is still necessary to provide an endpoint descriptor in the USB device framework
 * format, since most of this information is needed to program the underlying controller.
 * @param hBus the bus "handle"
 * @param pEndpointDesc pointer to a suitable endpoint descriptor
 * @return non-NULL pipe handle on success
 * @return NULL on failure (no compatible local endpoint resource or out of memory)
 */
extern MUSB_Pipe MUSB_BindFunctionEnd(MUSB_BusHandle hBus, 
				      const MUSB_EndpointDescriptor* pEndpointDesc);

/**
 * (Advanced) Close a function pipe.
 * Most clients will not need this function, since the automatically-opened
 * pipes are automatically closed when appropriate (alternate interface setting selected,
 * different configuration selected, or device unconfigured).
 * However, if a function does not use the USB device framework mechanism
 * to describe its endpoints, it should use this call at appropriate times
 * to close pipes it opened via MUSB_BindFunctionEnd.
 * @param hPipe pipe "handle"
 */
extern void MUSB_CloseFunctionPipe(MUSB_Pipe hPipe);

/**
 * Declare device unsupported.
 * A host-role client calls this after accepting the given device
 * in the device-connection callback, and subsequently determining that
 * it does not actually support the device.
 * @param hBus the bus "handle"
 * @param pDevice the rejected device
 */
extern void MUSB_RejectDevice(MUSB_BusHandle hBus, MUSB_Device* pDevice);

#if 0
/**
 * Declare interfaces unsupported.
 * A host-role client wishing to support compound devices calls this 
 * when there are interfaces in the configuration that it does not support.
 * The UCD will construct a virtual device/config including only these 
 * interface descriptors (and any that follow them), and run driver selection
 * on the new virtual device, giving other drivers the opportunity to use it.
 * @param hBus the bus "handle"
 * @param pDevice device pointer
 * @param abInterfaceNumber array of unclaimed interface numbers
 * @param bInterfaceCount the count of elements in abInterfaceNumber
 */
extern void MUSB_RejectInterfaces(MUSB_BusHandle hBus, MUSB_Device* pDevice,
				  uint8_t* abInterfaceNumber, uint8_t bInterfaceCount);

#endif /*0*/

/**
 * Enumerate a device on a hub port.
 * @param pHubDevice the hub's device pointer
 * @param bHubPort the hub port number
 * @param bSpeed device speed
 * @param pfHubEnumerateDevice completion callback
 * @return status code
 */
extern uint32_t MUSB_EnumerateDevice(MUSB_Device* pHubDevice, uint8_t bHubPort,
	uint8_t bSpeed, MUSB_pfHubEnumerationComplete pfHubEnumerateDevice);

#if 0
/**
 * Set the suspend state for a hub port (and therefore the bus behind it).
 * @param pHubDevice the hub's device pointer
 * @param bHubPort the hub port number
 * @param bSuspend TRUE to suspend the hub port;
 * FALSE to resume a previously-suspended hub port
 * @return status code
 */
extern uint32_t MUSB_SetTreeSuspend(MUSB_Device* pHubDevice, uint8_t bHubPort,
				    uint8_t bSuspend);

#endif /*0*/

/**
 * A device has been disconnected.
 * @param pDevice device pointer
 */
extern void MUSB_DeviceDisconnected(MUSB_Device* pDevice);

/**
 * Open a pipe as host.
 * Host clients call this to establish a virtual path to communicate
 * with a remote endpoint.
 * Resources for Interrupt and Isochronous remote endpoints
 * are bound to the pipe; other types may be shared.
 *
 * @param hBus the bus "handle"
 * @param pRemoteEnd pointer to a description of the desired remote endpoint
 * @param pEndpointResource if non-NULL, points to desired resource properties
 * upon call, and updated upon return
 *
 * @return non-NULL pipe "handle" on success
 */
extern MUSB_Pipe MUSB_OpenPipe(MUSB_BusHandle hBus,
			       const MUSB_DeviceEndpoint* pRemoteEnd,
			       MUSB_EndpointResource* pEndpointResource);

/**
 * Respond to host request.
 * Send a response to a host request on the default endpoint.
 * @param hBus the bus "handle"
 * @param dwSequenceNumber sequence number from request callback
 * @param pResonseData buffer of response data, relevant if request was IN
 * @param wResponseDataLength length of buffer
 * @param bStall TRUE to send the STALL handshake
 * @return status code
 */
extern uint32_t MUSB_DeviceResponse(MUSB_BusHandle hBus, uint32_t dwSequenceNumber,
	const uint8_t* pResponseData, uint16_t wResponseDataLength, uint8_t bStall);

/**
 * Close a pipe.
 * @param hPipe pipe "handle"
 * @return 0 on success; error code otherwise
 */
extern uint32_t MUSB_ClosePipe(MUSB_Pipe hPipe);

#if 0
/**
 * Get whether a pipe is halted.
 * @param hPipe pipe "handle"
 * @return TRUE if the pipe is halted; FALSE otherwise
 */
extern uint8_t MUSB_GetPipeHalt(MUSB_Pipe hPipe);

#endif /*0*/

/**
 * Set whether a pipe is halted.
 * @param hPipe pipe "handle"
 * @param TRUE to halt pipe; FALSE to resume it
 * @return 0 on success; error code otherwise
 */
extern uint32_t MUSB_SetPipeHalt(MUSB_Pipe hPipe, uint8_t bHalt);

/**
 * Flush the given pipe.
 * @param hPipe pipe "handle"
 * @return 0 on success; error code otherwise
 */
extern uint32_t MUSB_FlushPipe(MUSB_Pipe hPipe);

#if 0
/**
 * Allocate a DMA buffer for use with the given pipe.
 * @param hPipe pipe "handle"
 * @param dwLength requested buffer size, in bytes
 * @return non-NULL buffer on success; NULL on failure
 */
extern uint8_t* MUSB_AllocDmaBuffer(MUSB_Pipe hPipe, uint32_t dwLength);

/**
 * Free a previously-allocated DMA buffer.
 * @param hPipe pipe "handle"
 * @param pBuffer buffer pointer
 */
extern void MUSB_FreeDmaBuffer(MUSB_Pipe hPipe, uint8_t* pBuffer);

#endif /*0*/

/**
 * Start a single control transfer.
 *
 * @param pPort port pointer
 * @param pIrp pointer to the control IRP
 *
 * @return 0 on success; error code on failure
 */
extern uint32_t MUSB_StartControlTransfer(MUSB_Port* pPort, MUSB_ControlIrp* pIrp);

/**
 * Cancel a control transfer
 *
 * @param pPort port pointer
 * @param pIrp pointer to the control IRP
 *
 * @return 0 on success; error code on failure
 */
extern uint32_t MUSB_CancelControlTransfer(MUSB_Port* pPort, MUSB_ControlIrp* pIrp);

/**
 * Initiate bulk or interrupt traffic.
 * Start a single bulk transfer, or schedule an interrupt transfer.
 * Interrupt transfers remain scheduled until cancelled.
 *
 * @param pIrp pointer to the IRP
 *
 * @return 0 on success; error code on failure
 */
extern uint32_t MUSB_StartTransfer(MUSB_Irp* pIrp);

#if 0
/**
 * Update interrupt data.
 * Signal that new interrupt data is ready for transmission
 *
 * @param pIrp pointer to an interrupt-transmitting IRP
 *
 * @return 0 on success; error code on failure
 */
extern uint32_t MUSB_InterruptReady(MUSB_Irp* pIrp);

#endif /*0*/

/**
 * Cancel a bulk/interrupt transfer.
 * @param pIrp pointer to the IRP
 * @return 0 on success; error code on failure
 */
extern uint32_t MUSB_CancelTransfer(MUSB_Irp* pIrp);

/**
 * Schedule an isochronous transfer.
 * Upon success, it will remain scheduled until cancelled.
 * The IRP is essentially a ring buffer,
 * so the application is expected to partially fill/empty
 * it when its completion handler is called.
 *
 * @param dwWaitCount how many (micro)frames to wait before starting
 * @param pIsochIrp pointer to the IRP
 *
 * @return 0 on success; error code on failure
 */
extern uint32_t MUSB_ScheduleIsochTransfer(
    uint32_t dwWaitCount, MUSB_IsochIrp* pIsochIrp);

/**
 * Resynchronize isochronous traffic.
 * Move the imaginary reference frame synchronizing the given
 * isochronous transfer.
 *
 * @param wFrameAdjustment Adjustment, in frames.
 * Positive numbers insert delays, while negative numbers cause 
 * the transfer to occur earlier.
 * @param pIsochIrp pointer to the IRP
 *
 * @return 0 on success; error code on failure
 */
extern uint32_t MUSB_AdjustIsochTransfer(int16_t wFrameAdjustment, 
					 MUSB_IsochIrp* pIsochIrp);
/**
 * Cancel an isochronous transfer.
 *
 * @param pIsochIrp pointer to the IRP
 *
 * @return 0 on success; error code on failure
 */
extern uint32_t MUSB_CancelIsochTransfer(MUSB_IsochIrp* pIsochIrp);

#if 0
/**
 * Set diagnostics level.
 * Set the diagnostics level if compiled with diagnostics capability
 * (MUSB_DIAG > 0).
 * If compiled with MUSB_DIAG undefined or 0, this call has no effect.
 * @param bLevel 0 to disable diagnostics, 1 for some messages,
 * 2 for more messages, 3 for the most
 */
extern void MUSB_SetDiagnosticLevel(uint8_t bLevel);

#endif /*0*/

/**
 * Arm a one-shot timer.
 * This is specifically intended for use by class drivers.
 *
 * @param hBus bus "handle"
 * @param pDriver driver pointer
 * @param bTimerIndex the 0-based index from the driver's bTimerCount
 * @param dwTime timeout (milliseconds)
 * @param pParam parameter to expiration callback
 * @return 0 on success; error code on failure
 */
extern uint32_t MUSB_ArmTimer(MUSB_BusHandle hBus, MUSB_DeviceDriver* pDriver, 
	uint8_t bTimerIndex, uint32_t dwTime, 
	MUSB_pfDriverTimerExpired pfDriverTimerExpired, void* pParam);

#if 0
/**
 * Disarm a one-shot timer.
 * This is specifically intended for use by class drivers.
 *
 * @param hBus bus "handle"
 * @param pDriver the driver which armed the timer
 * @param bTimerIndex the 0-based index from the driver's bTimerCount
 * @return 0 on success; error code on failure
 */
extern uint32_t MUSB_CancelTimer(MUSB_BusHandle hBus, 
	MUSB_DeviceDriver* pDriver, uint8_t bTimerIndex);

#endif /*0*/

#endif	/* multiple inclusion protection */