diff --git a/platform/USBPhy.h b/platform/USBPhy.h index 1e800e33fc..ef2c91a096 100644 --- a/platform/USBPhy.h +++ b/platform/USBPhy.h @@ -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 */