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
*
* # Defined behavior
* * Any endpoint configurations which fit in the parameters of the table returned
* by USBPhy::endpoint_table can be used.
* * All endpoints in any valid endpoint configuration can be used concurrently
* * Device supports use of at least one control, bulk, interrupt and
* * You can use any endpoint configurations that fit in the parameters
* of the table returned by USBPhy::endpoint_table.
* * You can use all endpoints in any valid endpoint configuration concurrently.
* * The device supports use of at least one control, bulk, interrupt and
* isochronous in each direction at the same time - at least 8 endpoints.
* * Device 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
* * USBPhyEvents events are only sent when USBPhy is in the initialized state
* * When unpowered only the USBPhyEvents::power event can be sent
* * On USB reset all endpoints are removed except for endpoint 0
* * USBPhyEvents::out and USBPhyEvents::in events only occur for endpoints which have been added
* * A call to USBPhy::ep0_write results in USBPhyEvents::in getting called if not
* interrupted by a power loss or reset
* * A call to endpoint_read followed by endpoint_read_result results in USBPhyEvents::out getting called if not
* interrupted by a power loss or reset
* * Endpoint 0 naks all transactions aside from setup packets until one
* of ep0_read, ep0_write or ep0_stall has been called
* * Endpoint 0 stall is automatically cleared on reception of a setup packet
* * USBPhy supports all standard endpoint sizes (wMaxPacketSize).
* * USBPhy can handle an interrupt latency of at least 100ms if the host PC
* is not performing a reset or setting the device's address.
* * USBPhy only sends USBPhyEvents when it is in the initialized state.
* * When unpowered, USBPhy only sends the USBPhyEvents::power event.
* * On USB reset, all endpoints are removed except for endpoint 0.
* * A call to USBPhy::ep0_write results in the call of USBPhyEvents::in when
* the PC reads the data unless a power loss, reset, or a call to
* USBPhy::disconnect occurs first.
* * A call to USBPhy::endpoint_write results in the call of USBPhyEvents::in
* when the pc reads the data unless a power loss, reset, or a call to
* USBPhy::endpoint_abort occurs first.
* * 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
* * Calling USBPhy::endpoint_add or USBPhy::endpoint_remove outside of the control requests SetInterface or SetConfiguration
* * 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
* * Calling USBPhy::endpoint_add or USBPhy::endpoint_remove outside of the
* control requests SetInterface or SetConfiguration.
* * Calling USBPhy::endpoint_remove on an endpoint that has an ongoing read
* 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
* * Make sure USB packets are processed in the correct order when multiple packets are present.
* Typically IN endpoints should be handled before OUT endpoints if both are pending.
* * Setup packets may be resent if there is noise on the USB line. The USBPhy should be able
* to gracefully handle this scenario and respond to the setup packet with an ACK.
* * Bi-directional protocols making use of alternating IN and OUT phases should not rely
* on the last ACK an IN transfer to indicate that the OUT phase should start. Instead,
* the OUT phase should be started at 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 get re-sent on the next IN phase. More info on this can be
* found in section 8.5.3.3 of the USB spec.
* * Make sure USBPhy sends USBPhyEvents in the correct order when multiple
* packets are present. USBPhy must send IN endpoint events before OUT
* endpoint events if both are pending.
* * A host PC may resend setup packets to a USB device if there is noise on
* the USB line. The USBPhy should be able to handle this scenario and
* respond to the setup packet with an ACK.
* * Bidirectional protocols making use of alternating IN and OUT phases
* should not rely on the last ACK an IN transfer to indicate that the
* OUT phase should start. Instead, the OUT phase should be started at
* 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
*/