181 lines
7.8 KiB
Plaintext
181 lines
7.8 KiB
Plaintext
/*
|
|
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
|
|
*/
|