/*
    ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
*/

/**
 * @defgroup USB USB Driver
 * @brief   Generic USB Driver.
 * @details This module implements a generic USB (Universal Serial Bus) driver
 *          supporting device-mode operations.
 * @pre     In order to use the USB driver the @p HAL_USE_USB option
 *          must be enabled in @p halconf.h.
 *
 * @section usb_1 Driver State Machine
 * The driver implements a state machine internally, not all the driver
 * functionalities can be used in any moment, any transition not explicitly
 * shown in the following diagram has to be considered an error and shall
 * be captured by an assertion (if enabled).
 * @if LATEX_PDF
 * @dot
  digraph example {
    size="5, 7";
    rankdir="LR";
    node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true",
          width="0.9", height="0.9"];
    edge [fontname=Helvetica, fontsize=8];

    stop  [label="USB_STOP\nLow Power"];
    uninit [label="USB_UNINIT", style="bold"];
    ready [label="USB_READY\nClock Enabled"];
    selected [label="\nUSB_SELECTED\naddress\nassigned"];
    active [label="\nUSB_ACTIVE\nconfiguration\nselected"];

    uninit -> stop [label=" usbInit()", constraint=false];
    stop -> stop [label="\nusbStop()"];
    stop -> ready [label="\nusbStart()"];
    ready -> stop [label="\nusbStop()"];
    ready -> ready [label="\n\nusbStart()"];
    ready -> ready [label="\nSUSPEND/WAKEUP\n>event_cb<"];
    ready -> selected [label="\nSET_ADDRESS\n>event_cb<"];
    selected -> stop [label="\nusbStop()"];
    selected -> ready [label="\nUSB RESET\n>event_cb<"];
    selected -> selected [label="\nSUSPEND/WAKEUP\n>event_cb<\n\nValid EP0 Message\n>requests_hook_cb<\n\nGET DESCRIPTOR\n>get_descriptor_cb<"];
    selected -> active [label="\nSET_CONF(n)\n>event_cb<"];
    active -> stop [label="\nusbStop()"];
    active -> selected [label="\nSET_CONF(0)\n>event_cb<"];
    active -> active [label="\nSUSPEND/WAKEUP\n>event_cb<\n\nValid EP0 Message\n>requests_hook_cb<\n\nGET DESCRIPTOR\n>get_descriptor_cb<\n\nEndpoints Activity\n >in_cb< or >out_cb<"];
    active -> ready [label="\nUSB RESET\n>event_cb<"];
  }
 * @enddot
 * @else
 * @dot
  digraph example {
    rankdir="LR";
    node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true",
          width="0.9", height="0.9"];
    edge [fontname=Helvetica, fontsize=8];

    stop  [label="USB_STOP\nLow Power"];
    uninit [label="USB_UNINIT", style="bold"];
    ready [label="USB_READY\nClock Enabled"];
    selected [label="\nUSB_SELECTED\naddress\nassigned"];
    active [label="\nUSB_ACTIVE\nconfiguration\nselected"];

    uninit -> stop [label=" usbInit()", constraint=false];
    stop -> stop [label="\nusbStop()"];
    stop -> ready [label="\nusbStart()"];
    ready -> stop [label="\nusbStop()"];
    ready -> ready [label="\n\nusbStart()"];
    ready -> ready [label="\nSUSPEND/WAKEUP\n>event_cb<"];
    ready -> selected [label="\nSET_ADDRESS\n>event_cb<"];
    selected -> stop [label="\nusbStop()"];
    selected -> ready [label="\nUSB RESET\n>event_cb<"];
    selected -> selected [label="\nSUSPEND/WAKEUP\n>event_cb<\n\nValid EP0 Message\n>requests_hook_cb<\n\nGET DESCRIPTOR\n>get_descriptor_cb<"];
    selected -> active [label="\nSET_CONF(n)\n>event_cb<"];
    active -> stop [label="\nusbStop()"];
    active -> selected [label="\nSET_CONF(0)\n>event_cb<"];
    active -> active [label="\nSUSPEND/WAKEUP\n>event_cb<\n\nValid EP0 Message\n>requests_hook_cb<\n\nGET DESCRIPTOR\n>get_descriptor_cb<\n\nEndpoints Activity\n >in_cb< or >out_cb<"];
    active -> ready [label="\nUSB RESET\n>event_cb<"];
  }
 * @enddot
 * @endif
 *
 * @section usb_2 USB Operations
 * The USB driver is quite complex and USB is complex in itself, it is
 * recommended to study the USB specification before trying to use the
 * driver.
 *
 * @subsection usb_2_1 USB Implementation
 * The USB driver abstracts the inner details of the underlying USB hardware.
 * The driver works asynchronously and communicates with the application
 * using callbacks. The application is responsible of the descriptors and
 * strings required by the USB device class to be implemented and of the
 * handling of the specific messages sent over the endpoint zero. Standard
 * messages are handled internally to the driver. The application can use
 * hooks in order to handle custom messages or override the handling of the
 * default handling of standard messages.
 *
 * @subsection usb_2_2 USB Endpoints
 * USB endpoints are the objects that the application uses to exchange
 * data with the host. There are two kind of endpoints:
 * - <b>IN</b> endpoints are used by the application to transmit data to
 *   the host.<br>
 * - <b>OUT</b> endpoints are used by the application to receive data from
 *   the host.
 * .
 * The driver invokes a callback after finishing an IN or OUT transaction.
 * States diagram for OUT endpoints in transaction mode:
 * @dot
  digraph example {
    rankdir="LR";
    node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true",
          width="0.9", height="0.9"];
    edge [fontname=Helvetica, fontsize=8];

    disabled [label="EP_DISABLED\nDisabled", style="bold"];
    receiving [label="EP_BUSY\nReceiving"];
    idle [label="EP_IDLE\nReady"];

    disabled -> idle [label="\nusbInitEndpointI()"];
    idle -> receiving [label="\nusbPrepareReceive()\nusbStartReceiveI()"];
    receiving -> receiving [label="\nmore packets"];
    receiving -> idle [label="\nreception end\n>out_cb<"];
    receiving -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"];
    idle -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"];
  }
 * @enddot
 * <br><br>
 * States diagram for IN endpoints in transaction mode:
 * @dot
  digraph example {
    rankdir="LR";
    node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true",
          width="0.9", height="0.9"];
    edge [fontname=Helvetica, fontsize=8];

    disabled [label="EP_DISABLED\nDisabled", style="bold"];
    transmitting [label="EP_BUSY\nTransmitting"];
    idle [label="EP_IDLE\nReady"];

    disabled -> idle [label="\usbInitEndpointI()"];
    idle -> transmitting [label="\nusbPrepareTransmit()\nusbStartTransmitI()"];
    transmitting -> transmitting [label="\nmore packets"];
    transmitting -> idle [label="\ntransmission end\n>in_cb<"];
    transmitting -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"];
    idle -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"];
  }
 * @enddot
 * <br><br>
 *
 * @subsection usb_2_4 USB Callbacks
 * The USB driver uses callbacks in order to interact with the application.
 * There are several kinds of callbacks to be handled:
 * - Driver events callback. As example errors, suspend event, reset event
 *   etc.
 * - Messages Hook callback. This hook allows the application to implement
 *   handling of custom messages or to override the default handling of
 *   standard messages on endpoint zero.
 * - Descriptor Requested callback. When the driver endpoint zero handler
 *   receives a GET DESCRIPTOR message and needs to send a descriptor to
 *   the host it queries the application using this callback.
 * - Start of Frame callback. This callback is invoked each time a SOF
 *   packet is received.
 * - Endpoint callbacks. Each endpoint informs the application about I/O
 *   conditions using those callbacks.
 * .
 *
 * @ingroup HAL_NORMAL_DRIVERS
 */