USBDevice: add documentation on USB suspend/resume to enter deep sleep

It is possible to temporarily suspend USB and safely preserve its
configuration. This is needed to allow a device to enter deep
sleep as a USBDevice instance prevents deep sleep. USB operation can be
suspended with `deinit` and restored with `connect`.

Author: hugueskamba

drivers/internal/USBDevice.h

@@ -97,6 +97,10 @@ class USBDevice: public  USBPhyEvents {
      * Power down this instance
      *
      * Disable interrupts and stop sending events.
+     * This method can be used for temporary power-saving; This call can allow
+     * USB to be temporarily disabled to permit power saving.
+     * However, it is up to the user to make sure all the
+     * transfers have concluded (for example when USB power is lost).
      */
     void deinit();
 
@@ -109,6 +113,8 @@ class USBDevice: public  USBPhyEvents {
 
     /**
     * Connect a device
+    * This method can also be used to resume USB operation when USB power is
+    * detected after it was suspended via USBDevice::deinit.
     */
     void connect();
 
@@ -256,6 +262,23 @@ class USBDevice: public  USBPhyEvents {
      */
     uint32_t write_finish(usb_ep_t endpoint);
 
+    /** Suspend USB operation
+     *
+     * Control the USB state. This is primarily intended
+     * for temporary power-saving; This call can
+     * allow pwm to be temporarily disabled to permit power saving without
+     * losing device state.
+     */
+    void suspend();
+
+    /** Resume USB operation
+     *
+     * Control the USB state. This is primarily intended
+     * to resume USB operations after a previous USBDevice::suspend call;
+     * This call restores the device state prior to suspension.
+     */
+    void resume();
+
     /*
     * Get device descriptor.
     *