ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update USBPhy doxygen 

Update USBPhy doxygen to pull in handbook copyedits. Also update the
docs to reflect the enhanced USBPhy API.
pull/9768/head
Russ Butler 2018-03-18 20:20:59 -05:00 committed by Russ Butler
parent 2708200a19
commit c0df783249
1 changed files with 47 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
platform/USBPhy.h
View File

@ -23,42 +23,58 @@
/** Abstract interface to physical USB hardware /** Abstract interface to physical USB hardware
* *
* # Defined behavior * # Defined behavior
* * Any endpoint configurations which fit in the parameters of the table returned * * You can use any endpoint configurations that fit in the parameters
* by USBPhy::endpoint_table can be used. * of the table returned by USBPhy::endpoint_table.
* * All endpoints in any valid endpoint configuration can be used concurrently * * You can use all endpoints in any valid endpoint configuration concurrently.
* * Device supports use of at least one control, bulk, interrupt and * * The device supports use of at least one control, bulk, interrupt and
* isochronous in each direction at the same time - at least 8 endpoints. * isochronous in each direction at the same time - at least 8 endpoints.
* * Device supports all standard endpoint sizes (wMaxPacketSize) * * USBPhy supports all standard endpoint sizes (wMaxPacketSize).
* * Device can handle an interrupt latency of at least 100ms if reset is not being performed and address is not being set * * USBPhy can handle an interrupt latency of at least 100ms if the host PC
* * USBPhyEvents events are only sent when USBPhy is in the initialized state * is not performing a reset or setting the device's address.
* * When unpowered only the USBPhyEvents::power event can be sent * * USBPhy only sends USBPhyEvents when it is in the initialized state.
* * On USB reset all endpoints are removed except for endpoint 0 * * When unpowered, USBPhy only sends the USBPhyEvents::power event.
* * USBPhyEvents::out and USBPhyEvents::in events only occur for endpoints which have been added * * On USB reset, all endpoints are removed except for endpoint 0.
* * A call to USBPhy::ep0_write results in USBPhyEvents::in getting called if not * * A call to USBPhy::ep0_write results in the call of USBPhyEvents::in when
* interrupted by a power loss or reset * the PC reads the data unless a power loss, reset, or a call to
* * A call to endpoint_read followed by endpoint_read_result results in USBPhyEvents::out getting called if not * USBPhy::disconnect occurs first.
* interrupted by a power loss or reset * * A call to USBPhy::endpoint_write results in the call of USBPhyEvents::in
* * Endpoint 0 naks all transactions aside from setup packets until one * when the pc reads the data unless a power loss, reset, or a call to
* of ep0_read, ep0_write or ep0_stall has been called * USBPhy::endpoint_abort occurs first.
* * Endpoint 0 stall is automatically cleared on reception of a setup packet * * A call to USBPhy::endpoint_read results in the call of USBPhyEvents::out
* when the pc sends data unless a power loss, reset, or a call to
* USBPhy::endpoint_abort occurs first.
* * Endpoint 0 naks all transactions aside from setup packets until
* higher-level code calls one of USBPhy::ep0_read, USBPhy::ep0_write or
* USBPhy::ep0_stall.
* * Endpoint 0 stall automatically clears on reception of a setup packet.
* *
* # Undefined behavior * # Undefined behavior
* * Calling USBPhy::endpoint_add or USBPhy::endpoint_remove outside of the control requests SetInterface or SetConfiguration * * Calling USBPhy::endpoint_add or USBPhy::endpoint_remove outside of the
* * Devices behavior is undefined if latency is greater than 2ms when address is being set - see USB spec 9.2.6.3 * control requests SetInterface or SetConfiguration.
* * Devices behavior is undefined if latency is greater than 10ms when a reset occurs - see USB spec 7.1.7.5 * * Calling USBPhy::endpoint_remove on an endpoint that has an ongoing read
* * Calling any of the USBPhy::endpoint_* functions on endpoint 0 * or write operation. To avoid undefined behavior, you must abort ongoing
* operations with USBPhy::endpoint_abort.
* * Devices behavior is undefined if latency is greater than 2ms when address
* is being set - see USB spec 9.2.6.3.
* * Devices behavior is undefined if latency is greater than 10ms when a
* reset occurs - see USB spec 7.1.7.5.
* * Calling any of the USBPhy::endpoint_* functions on endpoint 0.
* *
* # Notes * # Notes
* * Make sure USB packets are processed in the correct order when multiple packets are present. * * Make sure USBPhy sends USBPhyEvents in the correct order when multiple
* Typically IN endpoints should be handled before OUT endpoints if both are pending. * packets are present. USBPhy must send IN endpoint events before OUT
* * Setup packets may be resent if there is noise on the USB line. The USBPhy should be able * endpoint events if both are pending.
* to gracefully handle this scenario and respond to the setup packet with an ACK. * * A host PC may resend setup packets to a USB device if there is noise on
* * Bi-directional protocols making use of alternating IN and OUT phases should not rely * the USB line. The USBPhy should be able to handle this scenario and
* on the last ACK an IN transfer to indicate that the OUT phase should start. Instead, * respond to the setup packet with an ACK.
* the OUT phase should be started at the same time the last IN transfer is started. This * * Bidirectional protocols making use of alternating IN and OUT phases
* is because the ACK to the last in transfer may be dropped if there is noise on the USB * should not rely on the last ACK an IN transfer to indicate that the
* line. If dropped it will only get re-sent on the next IN phase. More info on this can be * OUT phase should start. Instead, the OUT phase should be started at
* found in section 8.5.3.3 of the USB spec. * the same time the last IN transfer is started. This is because the ACK
* to the last in transfer may be dropped if there is noise on the USB
* line. If dropped, it will only be resent on the next IN phase. You can
* find more information on this in section 8.5.3.3 of the USB
* specification.
* *
* @ingroup usb_device_core * @ingroup usb_device_core
*/ */