Update USBAudio

Update the USBAudio class to use the new USB API. This patch also adds
buffering and blocking functionality so it can be used in practice
from thread context.

usb/device/USBAudio/USBAudio.h

@@ -0,0 +1,375 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2018-2018 ARM Limited
+ *
+ * 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 USBAudio_H
+#define USBAudio_H
+
+/* These headers are included for child class. */
+#include "USBDescriptor.h"
+#include "USBDevice_Types.h"
+
+#include "USBDevice.h"
+#include "Callback.h"
+#include "OperationList.h"
+#include "ByteBuffer.h"
+#include "rtos/EventFlags.h"
+
+/**
+* USBAudio example
+*
+* @code
+* #include "mbed.h"
+* #include "USBAudio.h"
+*
+* // Audio loopback example use:
+* // 1. Select "Mbed Audio" as your sound device
+* // 2. Play a song or audio file
+* // 3. Record the output using a program such as Audacity
+*
+* int main() {
+*
+*     USBAudio audio(true, 44100, 2, 44100, 2);
+*
+*     printf("Looping audio\r\n");
+*     static uint8_t buf[128];
+*     while (true) {
+*         if (!audio.read(buf, sizeof(buf))) {
+*             memset(buf, 0, sizeof(buf));
+*         }
+*         audio.write(buf, sizeof(buf));
+*     }
+* }
+* @endcode
+*/
+class USBAudio: protected USBDevice {
+public:
+
+    enum AudioEvent {
+        Start,
+        Transfer,
+        End
+    };
+
+    /**
+    * Basic constructor
+    *
+    * Construct this object optionally connecting.
+    *
+    * @note Do not use this constructor in derived classes.
+    *
+    * @param connect Call connect on initialization
+    * @param frequency_rx frequency in Hz (default: 48000)
+    * @param channel_count_rx channel number (1 or 2) (default: 1)
+    * @param frequency_tx frequency in Hz (default: 8000)
+    * @param channel_count_tx channel number (1 or 2) (default: 1)
+    * @param buffer_ms time audio can be buffered without overflowing in milliseconds
+    * @param vendor_id Your vendor_id
+    * @param product_id Your product_id
+    * @param product_release Your product_release
+    */
+    USBAudio(bool connect=true, uint32_t frequency_rx = 48000, uint8_t channel_count_rx = 1, uint32_t frequency_tx = 8000, uint8_t channel_count_tx = 1, uint32_t buffer_ms=10, uint16_t vendor_id = 0x7bb8, uint16_t product_id = 0x1111, uint16_t product_release = 0x0100);
+
+    /**
+    * Fully featured constructor
+    *
+    * Construct this object with the supplied USBPhy and parameters. The user
+    * this object is responsible for calling connect() or init().
+    *
+    * @note Derived classes must use this constructor and call init() or
+    * connect() themselves. Derived classes should also call deinit() in
+    * their destructor. This ensures that no interrupts can occur when the
+    * object is partially constructed or destroyed.
+    *
+    * @param phy USB phy to use
+    * @param frequency_rx frequency in Hz (default: 48000)
+    * @param channel_count_rx channel number (1 or 2) (default: 1)
+    * @param frequency_tx frequency in Hz (default: 8000)
+    * @param channel_count_tx channel number (1 or 2) (default: 1)
+    * @param buffer_ms time audio can be buffered without overflowing in milliseconds
+    * @param vendor_id Your vendor_id
+    * @param product_id Your product_id
+    * @param product_release Your product_release
+    */
+    USBAudio(USBPhy *phy, uint32_t frequency_rx, uint8_t channel_count_rx, uint32_t frequency_tx, uint8_t channel_count_tx, uint32_t buffer_ms, uint16_t vendor_id, uint16_t product_id, uint16_t product_release);
+
+    /**
+     * Destroy this object
+     *
+     * Any classes which inherit from this class must call deinit
+     * before this destructor runs.
+     */
+    virtual ~USBAudio();
+
+    /**
+    * Connect USBAudio
+    */
+    void connect();
+
+    /**
+    * Disconnect USBAudio
+    *
+    * This unblocks all calls to read_ready and write_ready.
+    */
+    void disconnect();
+
+    /**
+    * Read audio data
+    *
+    * @param buf pointer on a buffer which will be filled with audio data
+    * @param size size to read
+    *
+    * @returns true if successful
+    */
+    bool read(uint8_t *buf, uint32_t size);
+
+    /**
+    * Nonblocking audio data read
+    *
+    * Read the available audio data.
+    *
+    * @param buf pointer on a buffer which will be filled with audio data
+    * @param size size to read
+    * @param actual size actually read
+    * @note This function is safe to call from USBAudio callbacks.
+    */
+    void read_nb(uint8_t *buf, uint32_t size, uint32_t *actual);
+
+    /**
+     * Return the number read packets dropped due to overflow
+     *
+     * @param clear Reset the overflow count back to 0
+     * @return Number of packets dropped due to overflow
+     */
+    uint32_t read_overflows(bool clear=false);
+
+    /**
+     * Check if the audio read channel is open
+     *
+     * @return true if the audio read channel open, false otherwise
+     */
+    bool read_ready();
+
+    /**
+     * Wait until the audio read channel is open
+     */
+    void read_wait_ready();
+
+    /**
+    * Write audio data
+    *
+    * @param buf pointer to audio data to write
+    * @param size size to write
+    *
+    * @returns true if successful
+    */
+    bool write(uint8_t *buf, uint32_t size);
+
+    /**
+    * Nonblocking audio data write
+    *
+    * Write the available audio data.
+    *
+    * @param buf pointer to audio data to write
+    * @param size size to write
+    * @param actual actual size written
+    * @note This function is safe to call from USBAudio callbacks.
+    */
+    void write_nb(uint8_t *buf, uint32_t size, uint32_t *actual);
+
+    /**
+     * Return the number write packets not sent due to underflow
+     *
+     * @param clear Reset the underflow count back to 0
+     * @return Number of packets that should have been
+     *         sent but weren't due to overflow
+     */
+    uint32_t write_underflows(bool clear=false);
+
+    /**
+     * Check if the audio write channel is open
+     *
+     * @return true if the audio write channel open, false otherwise
+     */
+    bool write_ready();
+
+    /**
+     * Wait until the audio write channel is open
+     */
+    void write_wait_ready();
+
+    /**
+    * Get current volume between 0.0 and 1.0
+    *
+    * @returns volume
+    */
+    float get_volume();
+
+    /** Attach a Callback to update the volume
+     *
+     * @param cb Callback to attach
+     *
+     */
+    void attach(Callback<void()> &cb);
+
+    /** attach a Callback to Tx Done
+     *
+     * @param cb Callback to attach
+     *
+     */
+    void attach_tx(Callback<void(AudioEvent)> &cb);
+
+    /** attach a Callback to Rx Done
+     *
+     * @param cb Callback to attach
+     *
+     */
+    void attach_rx(Callback<void(AudioEvent)> &cb);
+
+protected:
+
+    virtual void callback_state_change(DeviceState new_state);
+    virtual void callback_request(const setup_packet_t *setup);
+    virtual void callback_request_xfer_done(const setup_packet_t *setup, bool aborted);
+    virtual void callback_set_configuration(uint8_t configuration);
+    virtual void callback_set_interface(uint16_t interface, uint8_t alternate);
+
+    virtual const uint8_t *string_iproduct_desc();
+    virtual const uint8_t *string_iinterface_desc();
+    virtual const uint8_t *configuration_desc(uint8_t index);
+
+private:
+
+    class AsyncWrite;
+    class AsyncRead;
+
+    enum ChannelState {
+        Powerdown,
+        Closed,
+        Opened
+    };
+
+    void _init(uint32_t frequency_rx, uint8_t channel_count_rx, uint32_t frequency_tx, uint8_t channel_count_tx, uint32_t buffer_ms);
+
+    /*
+    * Call to rebuild the configuration descriptor
+    *
+    * This function should be called on creation or when any
+    * value that is part of the configuration descriptor
+    * changes.
+    * @note This function uses ~200 bytes of stack so
+    * make sure your stack is big enough for it.
+    */
+    void _build_configuration_desc();
+
+    void _receive_change(ChannelState new_state);
+    void _receive_isr(usb_ep_t ep);
+    void _send_change(ChannelState new_state);
+    void _send_isr_start();
+    void _send_isr_next_sync();
+    void _send_isr(usb_ep_t ep);
+
+    // has connect been called
+    bool _connected;
+
+    // audio volume
+    float _volume;
+
+    // mute state
+    uint8_t _mute;
+
+    // Volume Current Value
+    uint16_t _vol_cur;
+
+    // Volume Minimum Value
+    uint16_t _vol_min;
+
+    // Volume Maximum Value
+    uint16_t _vol_max;
+
+    // Volume Resolution
+    uint16_t _vol_res;
+
+    // callback to update volume
+    Callback<void()> _update_vol;
+
+    // callback transmit Done
+    Callback<void(AudioEvent)> _tx_done;
+
+    // callback receive Done
+    Callback<void(AudioEvent)> _rx_done;
+
+    // Number of times data was dropped due to an overflow
+    uint32_t _rx_overflow;
+
+    // Number of times data was not sent due to an underflow
+    uint32_t _tx_underflow;
+
+    // frequency in Hz
+    uint32_t _tx_freq;
+    uint32_t _rx_freq;
+
+    // mono, stereo,...
+    uint8_t _rx_channel_count;
+    uint8_t _tx_channel_count;
+
+    bool _tx_idle;
+    uint16_t _tx_frame_fract;
+    uint16_t _tx_whole_frames_per_xfer;
+    uint16_t _tx_fract_frames_per_xfer;
+
+    // size of the maximum packet for the isochronous endpoint
+    uint16_t _tx_packet_size_max;
+    uint16_t _rx_packet_size_max;
+
+    // Buffer used for the isochronous transfer
+    uint8_t *_tx_packet_buf;
+    uint8_t *_rx_packet_buf;
+
+    // Holding buffer
+    ByteBuffer _tx_queue;
+    ByteBuffer _rx_queue;
+
+    // State of the audio channels
+    ChannelState _tx_state;
+    ChannelState _rx_state;
+
+
+    // sample - a single PCM audio sample
+    // frame    - a group of samples from each channel
+    // packet   - a group of frames sent over USB in one transfer
+
+    // Blocking primitives
+    OperationList<AsyncWrite> _write_list;
+    OperationList<AsyncRead> _read_list;
+    rtos::EventFlags _flags;
+
+    // endpoint numbers
+    usb_ep_t _episo_out;    // rx endpoint
+    usb_ep_t _episo_in;     // tx endpoint
+
+    // channel config in the configuration descriptor: master, left, right
+    uint8_t _channel_config_rx;
+    uint8_t _channel_config_tx;
+
+    // configuration descriptor
+    uint8_t _config_descriptor[183];
+
+    // buffer for control requests
+    uint8_t _control_receive[2];
+
+};
+
+#endif

usb/device/USBAudio/USBAudio_Types.h

@@ -0,0 +1,95 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2018-2018 ARM Limited
+ *
+ * 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 USBAUDIO_TYPES_H
+#define USBAUDIO_TYPES_H
+
+
+#define DEFAULT_CONFIGURATION (1)
+
+// Audio Request Codes
+#define REQUEST_SET_CUR     0x01
+#define REQUEST_GET_CUR     0x81
+#define REQUEST_SET_MIN     0x02
+#define REQUEST_GET_MIN     0x82
+#define REQUEST_SET_MAX     0x03
+#define REQUEST_GET_MAX     0x83
+#define REQUEST_SET_RES     0x04
+#define REQUEST_GET_RES     0x84
+
+#define MUTE_CONTROL        0x01
+#define VOLUME_CONTROL      0x02
+
+
+// Audio Descriptor Sizes
+#define CONTROL_INTERFACE_DESCRIPTOR_LENGTH       0x09
+#define STREAMING_INTERFACE_DESCRIPTOR_LENGTH     0x07
+#define INPUT_TERMINAL_DESCRIPTOR_LENGTH          0x0C
+#define OUTPUT_TERMINAL_DESCRIPTOR_LENGTH         0x09
+#define FEATURE_UNIT_DESCRIPTOR_LENGTH            0x09
+#define STREAMING_ENDPOINT_DESCRIPTOR_LENGTH      0x07
+
+// Audio Format Type Descriptor Sizes
+#define FORMAT_TYPE_I_DESCRIPTOR_LENGTH   0x0b
+
+#define AUDIO_CLASS                       0x01
+#define SUBCLASS_AUDIOCONTROL             0x01
+#define SUBCLASS_AUDIOSTREAMING           0x02
+
+// Audio Descriptor Types
+#define INTERFACE_DESCRIPTOR_TYPE         0x24
+#define ENDPOINT_DESCRIPTOR_TYPE          0x25
+
+// Audio Control Interface Descriptor Subtypes
+#define CONTROL_HEADER                    0x01
+#define CONTROL_INPUT_TERMINAL            0x02
+#define CONTROL_OUTPUT_TERMINAL           0x03
+#define CONTROL_FEATURE_UNIT              0x06
+
+// USB Terminal Types
+#define TERMINAL_USB_STREAMING            0x0101
+
+// Predefined Audio Channel Configuration Bits
+// Mono
+#define CHANNEL_M                         0x0000
+#define CHANNEL_L                         0x0001  /* Left Front */
+#define CHANNEL_R                         0x0002  /* Right Front */
+
+// Feature Unit Control Bits
+#define CONTROL_MUTE                      0x0001
+#define CONTROL_VOLUME                    0x0002
+
+// Input Terminal Types
+#define TERMINAL_MICROPHONE               0x0201
+
+// Output Terminal Types
+#define TERMINAL_SPEAKER                  0x0301
+#define TERMINAL_HEADPHONES               0x0302
+
+// Audio Streaming Interface Descriptor Subtypes
+#define STREAMING_GENERAL                 0x01
+#define STREAMING_FORMAT_TYPE             0x02
+
+// Audio Data Format Type I Codes
+#define FORMAT_PCM                        0x0001
+
+// Audio Format Types
+#define FORMAT_TYPE_I                     0x01
+
+// Audio Endpoint Descriptor Subtypes
+#define ENDPOINT_GENERAL                  0x01
+
+#endif