USBCDC.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_H
00019 #define USBCDC_H
00020 
00021 /* These headers are included for child class. */
00022 #include "USBDescriptor.h"
00023 #include "USBDevice_Types.h"
00024 
00025 #include "USBDevice.h"
00026 #include "OperationList.h"
00027 
00028 class AsyncOp;
00029 
00030 /**
00031  * \defgroup drivers_USBCDC USBCDC class
00032  * \ingroup drivers-public-api-usb
00033  * @{
00034  */
00035 
00036 class USBCDC: public USBDevice {
00037 public:
00038 
00039     /**
00040     * Basic constructor
00041     *
00042     * Construct this object optionally connecting and blocking until it is ready.
00043     *
00044     * @note Do not use this constructor in derived classes.
00045     *
00046     * @param connect_blocking true to perform a blocking connect, false to start in a disconnected state
00047     * @param vendor_id Your vendor_id
00048     * @param product_id Your product_id
00049     * @param product_release Your product_release
00050     */
00051     USBCDC(bool connect_blocking = true, uint16_t vendor_id = 0x1f00, uint16_t product_id = 0x2012, uint16_t product_release = 0x0001);
00052 
00053     /**
00054     * Fully featured constructor
00055     *
00056     * Construct this object with the supplied USBPhy and parameters. The user
00057     * this object is responsible for calling connect() or init().
00058     *
00059     * @note Derived classes must use this constructor and call init() or
00060     * connect() themselves. Derived classes should also call deinit() in
00061     * their destructor. This ensures that no interrupts can occur when the
00062     * object is partially constructed or destroyed.
00063     *
00064     * @param phy USB phy to use
00065     * @param vendor_id Your vendor_id
00066     * @param product_id Your product_id
00067     * @param product_release Your product_release
00068     */
00069     USBCDC(USBPhy *phy, uint16_t vendor_id, uint16_t product_id, uint16_t product_release);
00070 
00071     /**
00072      * Destroy this object
00073      *
00074      * Any classes which inherit from this class must call deinit
00075      * before this destructor runs.
00076      */
00077     virtual ~USBCDC();
00078 
00079     /**
00080      * Check if this class is ready
00081      *
00082      * @return true if a terminal is connected, false otherwise
00083      */
00084     bool ready();
00085 
00086     /**
00087      * Block until the terminal is connected
00088      */
00089     void wait_ready();
00090 
00091     /*
00092     * Send a buffer
00093     *
00094     * This function blocks until the full contents have been sent.
00095     *
00096     * @param buffer buffer to be sent
00097     * @param size length of the buffer
00098     * @returns true if successful false if interrupted due to a state change
00099     */
00100     bool send(uint8_t *buffer, uint32_t size);
00101 
00102     /**
00103      * Send what there is room for
00104      *
00105      * @param buffer data to send
00106      * @param size maximum number of bytes to send
00107      * @param actual a pointer to where to store the number of bytes sent
00108      * @param now true to start data transmission, false to wait
00109      */
00110     void send_nb(uint8_t *buffer, uint32_t size, uint32_t *actual, bool now = true);
00111 
00112     /*
00113     * Read a buffer from a certain endpoint. Warning: blocking
00114     *
00115     * Blocks until at least one byte of data has been read (actual != NULL) or
00116     * until the full size has been read (actual == NULL).
00117     *
00118     * @param buffer buffer where will be stored bytes
00119     * @param size the maximum number of bytes to read
00120     * @param actual A pointer to where to store the number of bytes actually read
00121     *   or NULL to read the full size
00122     * @returns true if successful false if interrupted due to a state change
00123     */
00124     bool receive(uint8_t *buffer, uint32_t size, uint32_t *actual = NULL);
00125 
00126     /**
00127      * Read from the receive buffer
00128      *
00129      * @param buffer buffer to fill with data
00130      * @param size maximum number of bytes read
00131      * @param actual a pointer to where to store the number of bytes actually received
00132      */
00133     void receive_nb(uint8_t *buffer, uint32_t size, uint32_t *actual);
00134 
00135 protected:
00136     /*
00137     * Get device descriptor. Warning: this method has to store the length of the report descriptor in reportLength.
00138     *
00139     * @returns pointer to the device descriptor
00140     */
00141     virtual const uint8_t *device_desc();
00142 
00143     /*
00144     * Get string product descriptor
00145     *
00146     * @returns pointer to the string product descriptor
00147     */
00148     virtual const uint8_t *string_iproduct_desc();
00149 
00150     /*
00151     * Get string interface descriptor
00152     *
00153     * @returns pointer to the string interface descriptor
00154     */
00155     virtual const uint8_t *string_iinterface_desc();
00156 
00157     /*
00158     * Get configuration descriptor
00159     *
00160     * @param index descriptor index
00161     * @returns pointer to the configuration descriptor
00162     */
00163     virtual const uint8_t *configuration_desc(uint8_t index);
00164 
00165     /*
00166     * Called by USBCallback_requestCompleted when CDC line coding is changed
00167     * Warning: Called in ISR
00168     *
00169     * @param baud The baud rate
00170     * @param bits The number of bits in a word (5-8)
00171     * @param parity The parity
00172     * @param stop The number of stop bits (1 or 2)
00173     */
00174     virtual void line_coding_changed(int baud, int bits, int parity, int stop) {};
00175 
00176     /*
00177      * Called when there is data that can be read
00178      */
00179     virtual void data_rx() {}
00180 
00181     /*
00182      * Called when there is space in the TX buffer
00183      */
00184     virtual void data_tx() {}
00185 
00186 protected:
00187 
00188     class AsyncWrite;
00189     class AsyncRead;
00190     class AsyncWait;
00191 
00192     virtual void callback_reset();
00193     virtual void callback_state_change(DeviceState new_state);
00194     virtual void callback_request(const setup_packet_t *setup);
00195     virtual void callback_request_xfer_done(const setup_packet_t *setup, bool aborted);
00196     virtual void callback_set_configuration(uint8_t configuration);
00197     virtual void callback_set_interface(uint16_t interface, uint8_t alternate);
00198 
00199     void _init();
00200 
00201     void _change_terminal_connected(bool connected);
00202 
00203     void _send_isr_start();
00204     void _send_isr();
00205 
00206     void _receive_isr_start();
00207     void _receive_isr();
00208 
00209     usb_ep_t _bulk_in;
00210     usb_ep_t _bulk_out;
00211     usb_ep_t _int_in;
00212 
00213     uint8_t _cdc_line_coding[7];
00214     uint8_t _cdc_new_line_coding[7];
00215     uint8_t _config_descriptor[75];
00216 
00217     OperationList<AsyncWait> _connected_list;
00218     bool _terminal_connected;
00219 
00220     OperationList<AsyncWrite> _tx_list;
00221     bool _tx_in_progress;
00222     uint8_t _tx_buffer[64];
00223     uint8_t *_tx_buf;
00224     uint32_t _tx_size;
00225 
00226     OperationList<AsyncRead> _rx_list;
00227     bool _rx_in_progress;
00228     uint8_t _rx_buffer[64];
00229     uint8_t *_rx_buf;
00230     uint32_t _rx_size;
00231 };
00232 
00233 /** @}*/
00234 
00235 #endif