USBCDC_ECM.h

00001 /*
00002  * Copyright (c) 2018-2019, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef USBCDC_ECM_H
00019 #define USBCDC_ECM_H
00020 
00021 #include "USBDescriptor.h"
00022 #include "USBDevice.h"
00023 #include "ByteBuffer.h"
00024 #include "Mutex.h"
00025 #include "EventFlags.h"
00026 #include "EventQueue.h"
00027 #include "Thread.h"
00028 #include "Callback.h"
00029 
00030 #define MAX_PACKET_SIZE_INT     (64)
00031 #define MAX_PACKET_SIZE_BULK    (64)
00032 #define MAX_PACKET_SIZE_EP0     (64)
00033 #define DEFAULT_CONFIGURATION   (1)
00034 
00035 #define PACKET_TYPE_PROMISCUOUS     (1<<0)
00036 #define PACKET_TYPE_ALL_MULTICAST   (1<<1)
00037 #define PACKET_TYPE_DIRECTED        (1<<2)
00038 #define PACKET_TYPE_BROADCAST       (1<<3)
00039 #define PACKET_TYPE_MULTICAST       (1<<4)
00040 
00041 /**
00042  * \defgroup drivers_USBCDC_ECM USBCDC_ECM class
00043  * \ingroup drivers-public-api-usb
00044  * @{
00045  */
00046 
00047 class USBCDC_ECM: public USBDevice {
00048 public:
00049 
00050     /**
00051     * Basic constructor
00052     *
00053     * Construct this object optionally connecting and blocking until it is ready.
00054     *
00055     * @note Do not use this constructor in derived classes.
00056     *
00057     * @param connect_blocking true to perform a blocking connect, false to start in a disconnected state
00058     * @param vendor_id Your vendor_id
00059     * @param product_id Your product_id
00060     * @param product_release Your product_release
00061     */
00062 
00063     USBCDC_ECM(bool connect_blocking = true, uint16_t vendor_id = 0x0700, uint16_t product_id = 0x0101, uint16_t product_release = 0x0001);
00064 
00065     /**
00066     * Fully featured constructor
00067     *
00068     * Construct this object with the supplied USBPhy and parameters. The user
00069     * this object is responsible for calling connect() or init().
00070     *
00071     * @note Derived classes must use this constructor and call init() or
00072     * connect() themselves. Derived classes should also call deinit() in
00073     * their destructor. This ensures that no interrupts can occur when the
00074     * object is partially constructed or destroyed.
00075     *
00076     * @param phy USB phy to use
00077     * @param vendor_id Your vendor_id
00078     * @param product_id Your product_id
00079     * @param product_release Your product_release
00080     */
00081     USBCDC_ECM(USBPhy *phy, uint16_t vendor_id, uint16_t product_id, uint16_t product_release);
00082 
00083     /**
00084      * Destroy this object
00085      *
00086      * Any classes which inherit from this class must call deinit
00087      * before this destructor runs.
00088      */
00089     virtual ~USBCDC_ECM();
00090 
00091     /**
00092      * Check if this class is ready
00093      *
00094      * @return true if configured, false otherwise
00095      */
00096     bool ready();
00097 
00098     /**
00099      * Block until this device is configured
00100      */
00101     void wait_ready();
00102 
00103     /**
00104     * Send a buffer
00105     *
00106     * This function blocks until the full contents have been sent.
00107     *
00108     * @param buffer buffer to be sent
00109     * @param size length of the buffer
00110     * @returns true if successful false if interrupted due to a state change
00111     */
00112     bool send(uint8_t *buffer, uint32_t size);
00113 
00114     /**
00115      * Read from the receive buffer
00116      *
00117      * @param buffer buffer to fill with data
00118      * @param size maximum number of bytes read
00119      * @param actual a pointer to where to store the number of bytes actually received
00120      */
00121     void receive_nb(uint8_t *buffer, uint32_t size, uint32_t *actual);
00122 
00123     /**
00124      * Return ethernet packet filter bitmap
00125      *
00126      * The Packet Filter is the inclusive OR of the bitmap
00127      * D0:   PACKET_TYPE_PROMISCUOUS
00128      * D1:   PACKET_TYPE_ALL_MULTICAST
00129      * D2:   PACKET_TYPE_DIRECTED
00130      * D3:   PACKET_TYPE_BROADCAST
00131      * D4:   PACKET_TYPE_MULTICAST
00132      * D5-D15: Reserved (zero)
00133      *
00134      * @return ethernet packet filter bitmap
00135      */
00136     uint16_t read_packet_filter();
00137 
00138     /**
00139      * Attach a callback for when an ethernet packet is received
00140      *
00141      * @param cb code to call when a packet is received
00142      */
00143     void attach_rx(mbed::Callback<void()> cb);
00144 
00145     /**
00146      * Attach a callback for when a request to configure device ethernet
00147      * packet filter is received
00148      *
00149      * @param cb code to call when a packet filter request is received
00150      */
00151     void attach_filter(mbed::Callback<void()> cb);
00152 
00153 protected:
00154 
00155     /*
00156     * Called when USB changes state
00157     *
00158     * @param new_state The new state of the USBDevice
00159     *
00160     * Warning: Called in ISR context
00161     */
00162     virtual void callback_state_change(DeviceState new_state);
00163 
00164     /*
00165     * This is used to handle extensions to standard requests
00166     * and class specific requests with a data phase
00167     */
00168     virtual void callback_request_xfer_done(const setup_packet_t *setup, bool aborted);
00169 
00170     /*
00171     * Called by USBDevice layer. Set configuration of the device.
00172     * For instance, you can add all endpoints that you need on this function.
00173     *
00174     * @param configuration Number of the configuration
00175     * @returns true if class handles this request
00176     */
00177     virtual void callback_set_configuration(uint8_t configuration);
00178 
00179     /*
00180     * Called by USBDevice layer in response to set_interface.
00181     *
00182     * Upon reception of this command endpoints of any previous interface
00183     * if any must be removed with endpoint_remove and new endpoint added with
00184     * endpoint_add.
00185     *
00186     * @param configuration Number of the configuration
00187     *
00188     * Warning: Called in ISR context
00189     */
00190     virtual void callback_set_interface(uint16_t interface, uint8_t alternate);
00191 
00192     /*
00193     * Get device descriptor.
00194     *
00195     * @returns pointer to the device descriptor
00196     */
00197     virtual const uint8_t *device_desc();
00198 
00199     /*
00200     * Get string product descriptor
00201     *
00202     * @returns pointer to the string product descriptor
00203     */
00204     virtual const uint8_t *string_iproduct_desc();
00205 
00206     /*
00207     * Get string configuration descriptor
00208     *
00209     * @returns pointer to the string configuration descriptor
00210     */
00211     virtual const uint8_t *string_iconfiguration_desc();
00212 
00213     /*
00214     * Get string serial descriptor
00215     *
00216     * @returns pointer to the string serial descriptor
00217     */
00218     virtual const uint8_t *string_iserial_desc();
00219 
00220     /*
00221     * Get configuration descriptor
00222     *
00223     * @returns pointer to the configuration descriptor
00224     */
00225     virtual const uint8_t *configuration_desc(uint8_t index);
00226 
00227     /*
00228     * This is used to handle extensions to standard requests
00229     * and class specific requests
00230     */
00231     virtual void callback_request(const setup_packet_t *setup);
00232 
00233     /*
00234     * Called by USBDevice layer on bus reset.
00235     *
00236     * complete_reset must be called after
00237     * the device is fully reset.
00238     *
00239     * Warning: Called in ISR context
00240     */
00241     virtual void callback_reset();
00242 
00243     uint8_t device_descriptor[18];
00244 
00245 private:
00246 
00247     usb_ep_t _int_in;
00248     usb_ep_t _bulk_in;
00249     usb_ep_t _bulk_out;
00250 
00251     uint8_t _config_descriptor[80];
00252     uint8_t _string_imac_addr[26];
00253 
00254     uint8_t _bulk_buf[MAX_PACKET_SIZE_BULK];
00255     uint16_t _packet_filter;
00256     ByteBuffer _rx_queue;
00257 
00258     rtos::EventFlags _flags;
00259     rtos::Mutex _write_mutex;
00260 
00261     events::EventQueue _queue;
00262     rtos::Thread _thread;
00263     mbed::Callback<void()> _callback_rx;
00264     mbed::Callback<void()> _callback_filter;
00265 
00266     void _init();
00267     void _int_callback();
00268     void _bulk_in_callback();
00269     void _bulk_out_callback();
00270     bool _notify_network_connection(uint8_t value);
00271     bool _notify_connection_speed_change(uint32_t up, uint32_t down);
00272     bool _write_bulk(uint8_t *buffer, uint32_t size);
00273     void _notify_connect();
00274 };
00275 
00276 /** @}*/
00277 
00278 #endif