stmhal: Add USB_VCP class/object, for direct USB VCP control.

Before, pyb.stdin/pyb.stdout allowed some kind of access to the USB VCP
device, but it was basic access.

This patch adds a proper USB_VCP class and object with much more control
over the USB VCP device.  Create an object with pyb.USB_VCP(), then use
this object as if it were a UART object.  It has send, recv, read,
write, and other methods.  send and recv allow a timeout to be specified.

Addresses issue 774.

stmhal/modpyb.c

@@ -367,6 +367,7 @@ STATIC const mp_map_elem_t pyb_module_globals_table[] = {
     { MP_OBJ_NEW_QSTR(MP_QSTR_have_cdc), (mp_obj_t)&pyb_have_cdc_obj },
     { MP_OBJ_NEW_QSTR(MP_QSTR_repl_uart), (mp_obj_t)&pyb_repl_uart_obj },
     { MP_OBJ_NEW_QSTR(MP_QSTR_hid), (mp_obj_t)&pyb_hid_send_report_obj },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_USB_VCP), (mp_obj_t)&pyb_usb_vcp_type },
 
     { MP_OBJ_NEW_QSTR(MP_QSTR_millis), (mp_obj_t)&pyb_millis_obj },
     { MP_OBJ_NEW_QSTR(MP_QSTR_delay), (mp_obj_t)&pyb_delay_obj },

stmhal/pybstdio.c

@@ -84,8 +84,10 @@ int stdin_rx_chr(void) {
         }
 #endif
 #endif
-        if (usb_vcp_rx_num() != 0) {
-            return usb_vcp_rx_get();
+
+        byte c;
+        if (usb_vcp_recv_byte(&c) != 0) {
+            return c;
         } else if (pyb_stdio_uart != PYB_UART_NONE && uart_rx_any(pyb_stdio_uart)) {
             return uart_rx_char(pyb_stdio_uart);
         }

stmhal/qstrdefsport.h

@@ -71,6 +71,12 @@ Q(millis)
 Q(seek)
 Q(tell)
 
+// for USB VCP class
+Q(USB_VCP)
+Q(send)
+Q(recv)
+Q(timeout)
+
 // for RTC class
 Q(RTC)
 Q(info)

stmhal/usb.c

@@ -32,10 +32,13 @@
 #include "usbd_cdc_interface.h"
 #include "usbd_msc_storage.h"
 
-#include "misc.h"
 #include "mpconfig.h"
+#include "misc.h"
 #include "qstr.h"
 #include "obj.h"
+#include "runtime.h"
+#include "stream.h"
+#include "bufhelper.h"
 #include "usb.h"
 
 #ifdef USE_DEVICE_MODE
@@ -99,18 +102,14 @@ void usb_vcp_set_interrupt_char(int c) {
     }
 }
 
-int usb_vcp_rx_num(void) {
-    return USBD_CDC_RxNum();
-}
-
-char usb_vcp_rx_get(void) {
-    return USBD_CDC_RxGet();
+int usb_vcp_recv_byte(uint8_t *c) {
+    return USBD_CDC_Rx(c, 1, 0);
 }
 
 void usb_vcp_send_strn(const char *str, int len) {
 #ifdef USE_DEVICE_MODE
     if (dev_is_enabled) {
-        USBD_CDC_Tx(str, len);
+        USBD_CDC_TxAlways((const uint8_t*)str, len);
     }
 #endif
 }
@@ -120,9 +119,9 @@ void usb_vcp_send_strn_cooked(const char *str, int len) {
     if (dev_is_enabled) {
         for (const char *top = str + len; str < top; str++) {
             if (*str == '\n') {
-                USBD_CDC_Tx("\r\n", 2);
+                USBD_CDC_TxAlways((const uint8_t*)"\r\n", 2);
             } else {
-                USBD_CDC_Tx(str, 1);
+                USBD_CDC_TxAlways((const uint8_t*)str, 1);
             }
         }
     }
@@ -135,6 +134,145 @@ void usb_hid_send_report(uint8_t *buf) {
 #endif
 }
 
+/******************************************************************************/
+// Micro Python bindings for USB VCP
+
+typedef struct _pyb_usb_vcp_obj_t {
+    mp_obj_base_t base;
+} pyb_usb_vcp_obj_t;
+
+STATIC const pyb_usb_vcp_obj_t pyb_usb_vcp_obj = {{&pyb_usb_vcp_type}};
+
+STATIC void pyb_usb_vcp_print(void (*print)(void *env, const char *fmt, ...), void *env, mp_obj_t self_in, mp_print_kind_t kind) {
+    print(env, "USB_VCP()");
+}
+
+STATIC mp_obj_t pyb_usb_vcp_make_new(mp_obj_t type_in, uint n_args, uint n_kw, const mp_obj_t *args) {
+    // check arguments
+    mp_arg_check_num(n_args, n_kw, 0, 0, false);
+
+    // return the USB VCP object
+    return (mp_obj_t)&pyb_usb_vcp_obj;
+}
+
+/// \method any()
+/// Return `True` if any characters waiting, else `False`.
+STATIC mp_obj_t pyb_usb_vcp_any(mp_obj_t self_in) {
+    if (USBD_CDC_RxNum() > 0) {
+        return mp_const_true;
+    } else {
+        return mp_const_false;
+    }
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_1(pyb_usb_vcp_any_obj, pyb_usb_vcp_any);
+
+/// \method send(data, *, timeout=5000)
+/// Send data over the USB VCP:
+///
+///   - `data` is the data to send (an integer to send, or a buffer object).
+///   - `timeout` is the timeout in milliseconds to wait for the send.
+///
+/// Return value: number of bytes sent.
+STATIC const mp_arg_t pyb_usb_vcp_send_args[] = {
+    { MP_QSTR_data,    MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} },
+    { MP_QSTR_timeout, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 5000} },
+};
+#define PYB_USB_VCP_SEND_NUM_ARGS MP_ARRAY_SIZE(pyb_usb_vcp_send_args)
+
+STATIC mp_obj_t pyb_usb_vcp_send(uint n_args, const mp_obj_t *args, mp_map_t *kw_args) {
+    // parse args
+    mp_arg_val_t vals[PYB_USB_VCP_SEND_NUM_ARGS];
+    mp_arg_parse_all(n_args - 1, args + 1, kw_args, PYB_USB_VCP_SEND_NUM_ARGS, pyb_usb_vcp_send_args, vals);
+
+    // get the buffer to send from
+    mp_buffer_info_t bufinfo;
+    uint8_t data[1];
+    pyb_buf_get_for_send(vals[0].u_obj, &bufinfo, data);
+
+    // send the data
+    int ret = USBD_CDC_Tx(bufinfo.buf, bufinfo.len, vals[1].u_int);
+
+    return mp_obj_new_int(ret);
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_KW(pyb_usb_vcp_send_obj, 1, pyb_usb_vcp_send);
+
+/// \method recv(data, *, timeout=5000)
+///
+/// Receive data on the bus:
+///
+///   - `data` can be an integer, which is the number of bytes to receive,
+///     or a mutable buffer, which will be filled with received bytes.
+///   - `timeout` is the timeout in milliseconds to wait for the receive.
+///
+/// Return value: if `data` is an integer then a new buffer of the bytes received,
+/// otherwise the number of bytes read into `data` is returned.
+STATIC mp_obj_t pyb_usb_vcp_recv(uint n_args, const mp_obj_t *args, mp_map_t *kw_args) {
+    // parse args
+    mp_arg_val_t vals[PYB_USB_VCP_SEND_NUM_ARGS];
+    mp_arg_parse_all(n_args - 1, args + 1, kw_args, PYB_USB_VCP_SEND_NUM_ARGS, pyb_usb_vcp_send_args, vals);
+
+    // get the buffer to receive into
+    mp_buffer_info_t bufinfo;
+    mp_obj_t o_ret = pyb_buf_get_for_recv(vals[0].u_obj, &bufinfo);
+
+    // receive the data
+    int ret = USBD_CDC_Rx(bufinfo.buf, bufinfo.len, vals[1].u_int);
+
+    // return the received data
+    if (o_ret == MP_OBJ_NULL) {
+        return mp_obj_new_int(ret); // number of bytes read into given buffer
+    } else {
+        return mp_obj_str_builder_end_with_len(o_ret, ret); // create a new buffer
+    }
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_KW(pyb_usb_vcp_recv_obj, 1, pyb_usb_vcp_recv);
+
+STATIC mp_uint_t pyb_usb_vcp_read(mp_obj_t self_in, void *buf, mp_uint_t size, int *errcode) {
+    int ret = USBD_CDC_Rx((byte*)buf, size, -1);
+    return ret;
+}
+
+STATIC mp_uint_t pyb_usb_vcp_write(mp_obj_t self_in, const void *buf, mp_uint_t size, int *errcode) {
+    int ret = USBD_CDC_Tx((const byte*)buf, size, -1);
+    return ret;
+}
+
+mp_obj_t pyb_usb_vcp___exit__(uint n_args, const mp_obj_t *args) {
+    return mp_const_none;
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(pyb_usb_vcp___exit___obj, 4, 4, pyb_usb_vcp___exit__);
+
+STATIC const mp_map_elem_t pyb_usb_vcp_locals_dict_table[] = {
+    { MP_OBJ_NEW_QSTR(MP_QSTR_send), (mp_obj_t)&pyb_usb_vcp_send_obj },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_recv), (mp_obj_t)&pyb_usb_vcp_recv_obj },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_read), (mp_obj_t)&mp_stream_read_obj },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_readall), (mp_obj_t)&mp_stream_readall_obj },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_readline), (mp_obj_t)&mp_stream_unbuffered_readline_obj},
+    { MP_OBJ_NEW_QSTR(MP_QSTR_write), (mp_obj_t)&mp_stream_write_obj },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_close), (mp_obj_t)&mp_identity_obj },
+    { MP_OBJ_NEW_QSTR(MP_QSTR___del__), (mp_obj_t)&mp_identity_obj },
+    { MP_OBJ_NEW_QSTR(MP_QSTR___enter__), (mp_obj_t)&mp_identity_obj },
+    { MP_OBJ_NEW_QSTR(MP_QSTR___exit__), (mp_obj_t)&pyb_usb_vcp___exit___obj },
+};
+
+STATIC MP_DEFINE_CONST_DICT(pyb_usb_vcp_locals_dict, pyb_usb_vcp_locals_dict_table);
+
+STATIC const mp_stream_p_t pyb_usb_vcp_stream_p = {
+    .read = pyb_usb_vcp_read,
+    .write = pyb_usb_vcp_write,
+};
+
+const mp_obj_type_t pyb_usb_vcp_type = {
+    { &mp_type_type },
+    .name = MP_QSTR_USB_VCP,
+    .print = pyb_usb_vcp_print,
+    .make_new = pyb_usb_vcp_make_new,
+    .getiter = mp_identity,
+    .iternext = mp_stream_unbuffered_iter,
+    .stream_p = &pyb_usb_vcp_stream_p,
+    .locals_dict = (mp_obj_t)&pyb_usb_vcp_locals_dict,
+};
+
 /******************************************************************************/
 // code for experimental USB OTG support
 

stmhal/usb.h

@@ -41,13 +41,14 @@ typedef enum {
     USB_STORAGE_MEDIUM_SDCARD,
 } usb_storage_medium_t;
 
+const mp_obj_type_t pyb_usb_vcp_type;
+
 void pyb_usb_dev_init(usb_device_mode_t mode, usb_storage_medium_t medium);
 void pyb_usb_dev_stop(void);
 bool usb_vcp_is_enabled(void);
 bool usb_vcp_is_connected(void);
 void usb_vcp_set_interrupt_char(int c);
-int usb_vcp_rx_num(void);
-char usb_vcp_rx_get(void);
+int usb_vcp_recv_byte(uint8_t *c);
 void usb_vcp_send_strn(const char* str, int len);
 void usb_vcp_send_strn_cooked(const char *str, int len);
 void usb_hid_send_report(uint8_t *buf); // 4 bytes for mouse: ?, x, y, ?

stmhal/usbd_cdc_interface.c

@@ -33,11 +33,18 @@
   */
 
 /* Includes ------------------------------------------------------------------*/
+
 #include <stdbool.h>
+
 #include "stm32f4xx_hal.h"
 #include "usbd_cdc_msc_hid.h"
 #include "usbd_cdc_interface.h"
 #include "pendsv.h"
+
+#include "mpconfig.h"
+#include "misc.h"
+#include "qstr.h"
+#include "obj.h"
 #include "usb.h"
 
 // CDC control commands
@@ -59,7 +66,7 @@
 /* Private macro -------------------------------------------------------------*/
 /* Private variables ---------------------------------------------------------*/
 
-static uint8_t dev_is_connected = 0; // indicates if we are connected
+static __IO uint8_t dev_is_connected = 0; // indicates if we are connected
 
 static uint8_t UserRxBuffer[APP_RX_DATA_SIZE]; // received data from USB OUT endpoint is stored in this buffer
 static uint16_t UserRxBufCur = 0; // points to next available character in UserRxBuffer
@@ -399,7 +406,34 @@ void USBD_CDC_SetInterrupt(int chr, void *data) {
     user_interrupt_data = data;
 }
 
-void USBD_CDC_Tx(const char *str, uint32_t len) {
+// timout in milliseconds.
+// Returns number of bytes written to the device.
+int USBD_CDC_Tx(const uint8_t *buf, uint32_t len, uint32_t timeout) {
+    for (uint32_t i = 0; i < len; i++) {
+        // Wait until the device is connected and the buffer has space, with a given timeout
+        uint32_t start = HAL_GetTick();
+        while (!dev_is_connected || ((UserTxBufPtrIn + 1) & (APP_TX_DATA_SIZE - 1)) == UserTxBufPtrOut) {
+            // Wraparound of tick is taken care of by 2's complement arithmetic.
+            if (HAL_GetTick() - start >= timeout) {
+                // timeout
+                return i;
+            }
+            __WFI(); // enter sleep mode, waiting for interrupt
+        }
+
+        // Write data to device buffer
+        UserTxBuffer[UserTxBufPtrIn] = buf[i];
+        UserTxBufPtrIn = (UserTxBufPtrIn + 1) & (APP_TX_DATA_SIZE - 1);
+    }
+
+    // Success, return number of bytes read
+    return len;
+}
+
+// Always write all of the data to the device tx buffer, even if the
+// device is not connected, or if the buffer is full.  Has a small timeout
+// to wait for the buffer to be drained, in the case the device is connected.
+void USBD_CDC_TxAlways(const uint8_t *buf, uint32_t len) {
     for (int i = 0; i < len; i++) {
         // If the CDC device is not connected to the host then we don't have anyone to receive our data.
         // The device may become connected in the future, so we should at least try to fill the buffer
@@ -433,23 +467,36 @@ void USBD_CDC_Tx(const char *str, uint32_t len) {
             */
         }
 
-        UserTxBuffer[UserTxBufPtrIn] = str[i];
+        UserTxBuffer[UserTxBufPtrIn] = buf[i];
         UserTxBufPtrIn = (UserTxBufPtrIn + 1) & (APP_TX_DATA_SIZE - 1);
     }
 }
 
+// Returns number of bytes in the rx buffer.
 int USBD_CDC_RxNum(void) {
     return UserRxBufLen - UserRxBufCur;
 }
 
-int USBD_CDC_RxGet(void) {
-    // wait for buffer to have at least 1 character in it
-    while (USBD_CDC_RxNum() == 0) {
-        __WFI();
+// timout in milliseconds.
+// Returns number of bytes read from the device.
+int USBD_CDC_Rx(uint8_t *buf, uint32_t len, uint32_t timeout) {
+    // loop to read bytes
+    for (uint32_t i = 0; i < len; i++) {
+        // Wait until we have at least 1 byte to read
+        uint32_t start = HAL_GetTick();
+        while (!dev_is_connected || UserRxBufLen == UserRxBufCur) {
+            // Wraparound of tick is taken care of by 2's complement arithmetic.
+            if (HAL_GetTick() - start >= timeout) {
+                // timeout
+                return i;
+            }
+            __WFI(); // enter sleep mode, waiting for interrupt
+        }
+
+        // Copy byte from device to user buffer
+        buf[i] = UserRxBuffer[UserRxBufCur++];
     }
 
-    // get next character
-    int c = UserRxBuffer[UserRxBufCur++];
-
-    return c;
+    // Success, return number of bytes read
+    return len;
 }

stmhal/usbd_cdc_interface.h

@@ -20,8 +20,8 @@
   *
   *        http://www.st.com/software_license_agreement_liberty_v2
   *
-  * Unless required by applicable law or agreed to in writing, software 
-  * distributed under the License is distributed on an "AS IS" BASIS, 
+  * 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.
@@ -36,6 +36,9 @@ void USBD_CDC_HAL_TIM_PeriodElapsedCallback(void);
 
 int USBD_CDC_IsConnected(void);
 void USBD_CDC_SetInterrupt(int chr, void *data);
-void USBD_CDC_Tx(const char *str, uint32_t len);
+
+int USBD_CDC_Tx(const uint8_t *buf, uint32_t len, uint32_t timeout);
+void USBD_CDC_TxAlways(const uint8_t *buf, uint32_t len);
+
 int USBD_CDC_RxNum(void);
-int USBD_CDC_RxGet(void);
+int USBD_CDC_Rx(uint8_t *buf, uint32_t len, uint32_t timeout);