Mbed OS Reference | USBDevice.h Source File

 /*
  * Copyright (c) 2018-2019, Arm Limited and affiliates.
  * SPDX-License-Identifier: Apache-2.0
  *
  * 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.
  */
 
 #ifndef USBDEVICE_H
 #define USBDEVICE_H
 
 #include <stddef.h>
 #include "USBDevice_Types.h"
 #include "USBPhy.h"
 #include "mbed_critical.h"
 #include "Callback.h"
 
 /**
  * \defgroup drivers_USBDevice USBDevice class
  * \ingroup drivers-internal-api-usb
  * @{
  */
 
 /**
  * Core USB Device driver
  *
  * USB driver which wraps and provides synchronization for a USBPhy object.
  */
 class USBDevice: public  USBPhyEvents {
 public:
     typedef void (USBDevice::*ep_cb_t)();
 
     enum RequestResult {
         Receive = 0,
         Send = 1,
         Success = 2,
         Failure = 3,
         PassThrough = 4,
     };
 
     enum DeviceState {
         Attached,
         Powered,
         Default,
         Address,
         Configured
     };
 
     struct setup_packet_t {
         struct {
             uint8_t dataTransferDirection;
             uint8_t Type;
             uint8_t Recipient;
         } bmRequestType;
         uint8_t  bRequest;
         uint16_t wValue;
         uint16_t wIndex;
         uint16_t wLength;
     };
 
     /**
      * Instantiate a new USBDevice with the given parameters
      *
      * @param phy The USBPhy providing physical USB access
      * @param vendor_id The USB vendor ID
      * @param product_id The USB product ID
      * @param product_release The device release number
      */
     USBDevice(USBPhy *phy, uint16_t vendor_id, uint16_t product_id, uint16_t product_release);
 
     /**
      * Cleanup this USBDevice
      *
      * This USBDevice must be uninitialized when the destructor is
      * called or the behavior is undefined.
      */
     virtual ~USBDevice();
 
     /**
      * Initialize this instance
      *
      * This function must be called before calling
      * any other functions of this class, unless specifically
      */
     void init();
 
     /**
      * 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).
      * USBDevice::connect can be used to resume USB operation.
      */
     void deinit();
 
     /**
     * Check if the device is configured
     *
     * @returns true if configured, false otherwise
     */
     bool configured();
 
     /**
     * 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();
 
     /**
     * Disconnect a device
     */
     void disconnect();
 
     /**
      * Enable the start of frame interrupt
      *
      * Call USBDevice::callback_sof on every frame.
      */
     void sof_enable();
 
     /**
      * Disable the start of frame interrupt
      *
      * Stop calling USBDevice::callback_sof.
      */
     void sof_disable();
 
     /**
     * Add an endpoint
     *
     * @param endpoint Endpoint to enable
     * @param max_packet Maximum size of a packet which can be sent or received on this endpoint
     * @param type Endpoint type - USB_EP_TYPE_BULK, USB_EP_TYPE_INT or USB_EP_TYPE_ISO
     * @param callback Method pointer to be called when a packet is transferred
     * @returns true if successful, false otherwise
     */
     bool endpoint_add(usb_ep_t endpoint, uint32_t max_packet, usb_ep_type_t type, mbed::Callback<void()> callback = nullptr);
 
     /**
     * Add an endpoint
     *
     * @param endpoint Endpoint to enable
     * @param max_packet Maximum size of a packet which can be sent or received on this endpoint
     * @param type Endpoint type - USB_EP_TYPE_BULK, USB_EP_TYPE_INT or USB_EP_TYPE_ISO
     * @param callback Method pointer to be called when a packet is transferred
     * @returns true if successful, false otherwise
     */
     template<typename T>
     bool endpoint_add(usb_ep_t endpoint, uint32_t max_packet, usb_ep_type_t type, void (T::*callback)())
     {
         return endpoint_add(endpoint, max_packet, type, mbed::callback(this, static_cast<ep_cb_t>(callback)));
     }
 
     /**
     * Remove an endpoint
     *
     * @param endpoint Endpoint to disable
     * @note This endpoint must already have been setup with endpoint_add
     */
     void endpoint_remove(usb_ep_t endpoint);
 
     /**
     * Remove all non-zero endpoints
     */
     void endpoint_remove_all();
 
     /**
     * Stall an endpoint
     *
     * If there is an ongoing transfer on this endpoint then it will
     * be aborted.
     *
     * @param endpoint Endpoint to stall
     * @note You cannot stall endpoint 0 with this function
     * @note This endpoint must already have been setup with endpoint_add
     */
     void endpoint_stall(usb_ep_t endpoint);
 
     /**
     * Un-stall an endpoint
     *
     * Un-stalling an endpoint resets data toggle back to DATA0.
     * Additionally, if there is an ongoing transfer on this endpoint
     * it will be aborted.
     *
     * @param endpoint Endpoint to un-stall
     * @note This endpoint must already have been setup with endpoint_add
     */
     void endpoint_unstall(usb_ep_t endpoint);
 
     /**
      * Get the current maximum size for this endpoint
      *
      * Return the currently configured maximum packet size, wMaxPacketSize,
      * for this endpoint.
      * @note This endpoint must already have been setup with endpoint_add
      */
     uint32_t endpoint_max_packet_size(usb_ep_t endpoint);
 
     /**
      * Abort the current transfer on this endpoint
      *
      * @param endpoint endpoint with transfer to abort
      * @note This endpoint must already have been setup with endpoint_add
      */
     void endpoint_abort(usb_ep_t endpoint);
 
     /**
      * start a read on the given endpoint
      *
      * Start a read on the given endpoint. The data buffer must remain
      * unchanged until the transfer either completes or is aborted.
      *
      * @param endpoint endpoint to read data from
      * @param buffer buffer to fill with read data
      * @param size The size of data to read. This must be greater than or equal
      *        to the max packet size for this endpoint
      * @return true if the read was completed, otherwise false
      * @note This endpoint must already have been setup with endpoint_add
      */
     bool read_start(usb_ep_t endpoint, uint8_t *buffer, uint32_t size);
 
     /**
      * Get the status of a read
      *
      * @param endpoint endpoint to get the status of
      * @return number of bytes read by this endpoint
      */
     uint32_t read_finish(usb_ep_t endpoint);
 
     /**
      * Write a data to the given endpoint
      *
      * Write data to an endpoint. The data sent must remain unchanged until
      * the transfer either completes or is aborted.
      *
      * @param endpoint endpoint to write data to
      * @param buffer data to write
      * @param size the size of data to send. This must be less than or equal to the
      * max packet size of this endpoint
      * @note This endpoint must already have been setup with endpoint_add
      */
     bool write_start(usb_ep_t endpoint, uint8_t *buffer, uint32_t size);
 
     /**
      * Get the status of a write
      *
      * @param endpoint endpoint to get the status of
      * @return number of bytes sent by this endpoint
      */
     uint32_t write_finish(usb_ep_t endpoint);
 
     /*
     * Get device descriptor.
     *
     * @returns pointer to the device descriptor
     */
     virtual const uint8_t *device_desc();
 
     /*
     * Get configuration descriptor
     *
     * @param index descriptor index
     * @returns pointer to the configuration descriptor
     */
     virtual const uint8_t *configuration_desc(uint8_t index) = 0;
 
     /*
     * Get string lang id descriptor
     *
     * @return pointer to the string lang id descriptor
     */
     virtual const uint8_t *string_langid_desc();
 
     /*
     * Get string manufacturer descriptor
     *
     * @returns pointer to the string manufacturer descriptor
     */
     virtual const uint8_t *string_imanufacturer_desc();
 
     /*
     * Get string product descriptor
     *
     * @returns pointer to the string product descriptor
     */
     virtual const uint8_t *string_iproduct_desc();
 
     /*
     * Get string serial descriptor
     *
     * @returns pointer to the string serial descriptor
     */
     virtual const uint8_t *string_iserial_desc();
 
     /*
     * Get string configuration descriptor
     *
     * @returns pointer to the string configuration descriptor
     */
     virtual const uint8_t *string_iconfiguration_desc();
 
     /*
     * Get string interface descriptor
     *
     * @returns pointer to the string interface descriptor
     */
     virtual const uint8_t *string_iinterface_desc();
 
     /*
     * Get the length of the report descriptor
     *
     * @returns length of the report descriptor
     */
     virtual uint16_t report_desc_dength()
     {
         return 0;
     };
 
 protected:
 
     /**
     * Called by USBDevice layer on power state change.
     *
     * @param powered true if device is powered, false otherwise
     *
     * Warning: Called in ISR context
     */
     virtual void callback_power(bool powered)
     {
 
     }
 
     /**
     * Called by USBDevice layer on each new USB frame.
     *
     * Callbacks are enabled and disabled by calling sof_enable
     * and sof_disable.
     *
     * @param frame_number The current frame number
     *
     * Warning: Called in ISR context
     */
     virtual void callback_sof(int frame_number)
     {
 
     }
 
     /**
     * Called by USBDevice layer on bus reset.
     *
     * complete_reset must be called after
     * the device is fully reset.
     *
     * Warning: Called in ISR context
     */
     virtual void callback_reset()
     {
 
     }
 
     /**
     * Called when USB changes state
     *
     * @param new_state The new state of the USBDevice
     *
     * Warning: Called in ISR context
     */
     virtual void callback_state_change(DeviceState new_state) = 0;
 
     /**
     * Called by USBDevice on Endpoint0 request.
     *
     * This is used to handle extensions to standard requests
     * and class specific requests. The function complete_request
     * must be always be called in response to this callback.
     *
     * Warning: Called in ISR context
     */
     virtual void callback_request(const setup_packet_t *setup) = 0;
 
     /**
      * Called to complete the setup stage of a callback request
      *
      * Possible options that can be passed as a result are:
      * - Receive - Start the data OUT phase of this control transfer
      * - Send - Start the data IN phase of this control transfer
      * - Success - Operation was a success so start the status phase
      * - Failure - Operation failed or is unsupported so send a stall
      * - PassThrough - Pass on the request for standard processing
      *
      * @param result The result of the setup phase.
      * @param data Buffer to send or receive if the result is Send or Receive
      * @param size Size to transfer if the result is Send or Receive
      */
     void complete_request(RequestResult result, uint8_t *data = NULL, uint32_t size = 0);
 
     /**
     * Called by USBDevice on data stage completion
     *
     * The function complete_request_xfer_done must be always be called
     * in response to this callback.
     *
     * @param setup Setup packet of the current request
     * @param aborted false if the operation was aborted, true otherwise
     *
     * Warning: Called in ISR context
     */
     virtual void callback_request_xfer_done(const setup_packet_t *setup, bool aborted) = 0;
 
     /**
      * Called to complete the data stage of a callback request
      *
      * @param success true if the operation was successful, false otherwise
      */
     void complete_request_xfer_done(bool success);
 
     /*
     * Called by USBDevice layer in response to set_configuration.
     *
     * Upon reception of this command endpoints of the previous configuration
     * if any must be removed with endpoint_remove and new endpoint added with
     * endpoint_add.
     *
     * @param configuration Number of the configuration
     *
     * Warning: Called in ISR context
     */
     virtual void callback_set_configuration(uint8_t configuration) = 0;
 
     /**
      * Called to complete a set configuration command
      *
      * @param success true if the configuration was set, false otherwise
      */
     void complete_set_configuration(bool success);
 
     /*
     * Called by USBDevice layer in response to set_interface.
     *
     * Upon reception of this command endpoints of any previous interface
     * if any must be removed with endpoint_remove and new endpoint added with
     * endpoint_add.
     *
     * @param configuration Number of the configuration
     *
     * Warning: Called in ISR context
     */
     virtual void callback_set_interface(uint16_t interface, uint8_t alternate) = 0;
 
     /**
      * Called to complete a set interface command
      *
      * @param success true if the interface was set, false otherwise
      */
     void complete_set_interface(bool success);
 
     /**
      * Find a descriptor type inside the configuration descriptor
      *
      * @param descriptor_type Type of descriptor to find
      * @param index Configuration descriptor index ( 0 if only one configuration present )
      * @return A descriptor of the given type or NULL if none were found
      */
     uint8_t *find_descriptor(uint8_t descriptor_type, uint8_t index = 0);
 
     /**
      * Get the endpoint table of this device
      *
      * @return Endpoint table of the USBPhy attached to this USBDevice
      */
     const usb_ep_table_t *endpoint_table();
 
     /**
      * Callback called to indicate the USB processing needs to be done
      */
     virtual void start_process();
 
     /**
      * Acquire exclusive access to this instance USBDevice
      */
     virtual void lock();
 
     /**
      * Release exclusive access to this instance USBDevice
      */
     virtual void unlock();
 
     /**
      * Assert that the current thread of execution holds the lock
      *
      */
     virtual void assert_locked();
 
     uint16_t vendor_id;
     uint16_t product_id;
     uint16_t product_release;
     uint8_t device_descriptor[18];
 
 private:
     // USBPhyEvents
     virtual void power(bool powered);
     virtual void suspend(bool suspended);
     virtual void sof(int frame_number);
     virtual void reset();
     virtual void ep0_setup();
     virtual void ep0_out();
     virtual void ep0_in();
     virtual void out(usb_ep_t endpoint);
     virtual void in(usb_ep_t endpoint);
 
     bool _request_get_descriptor();
     bool _control_out();
     bool _control_in();
     bool _request_set_address();
     bool _request_set_configuration();
     bool _request_set_feature();
     bool _request_clear_feature();
     bool _request_get_status();
     bool _request_setup();
     void _control_setup();
     void _control_abort();
     void _control_abort_start();
     void _control_setup_continue();
     void _decode_setup_packet(uint8_t *data, setup_packet_t *packet);
     bool _request_get_configuration();
     bool _request_get_interface();
     bool _request_set_interface();
     void _change_state(DeviceState state);
     void _run_later(void (USBDevice::*function)());
 
     void _complete_request();
     void _complete_request_xfer_done();
     void _complete_set_configuration();
     void _complete_set_interface();
 
     struct endpoint_info_t {
         mbed::Callback<void()> callback;
         uint16_t max_packet_size;
         uint16_t transfer_size;
         uint8_t flags;
         uint8_t pending;
     };
 
     struct usb_device_t {
         volatile DeviceState state;
         uint8_t configuration;
         bool suspended;
     };
 
     enum ControlState {
         Setup,
         DataOut,
         DataIn,
         Status
     };
 
     enum UserCallback {
         None,
         Request,
         RequestXferDone,
         SetConfiguration,
         SetInterface
     };
 
     struct complete_request_t {
         RequestResult result;
         uint8_t *data;
         uint32_t size;
     };
 
     union complete_args_t {
         complete_request_t request;
         bool status;
     };
 
     struct control_transfer_t {
         setup_packet_t setup;
         uint8_t *ptr;
         uint32_t remaining;
         uint8_t direction;
         bool zlp;
         bool notify;
         ControlState stage;
         UserCallback user_callback;
         complete_args_t args;
     };
 
     endpoint_info_t _endpoint_info[32 - 2];
 
     USBPhy *_phy;
     bool _initialized;
     bool _connected;
     bool _endpoint_add_remove_allowed;
     control_transfer_t _transfer;
     usb_device_t _device;
     uint32_t _max_packet_size_ep0;
     void (USBDevice::*_post_process)();
 
     bool _setup_ready;
     bool _abort_control;
 
     uint16_t _current_interface;
     uint8_t _current_alternate;
     uint32_t _locked;
 };
 
 /** @}*/
 
 #endif
Important Information for this Arm website
