SAMV71 Xplained Ultra Software Package 1.5

AUDDSpeakerPhoneDriver.h

Go to the documentation of this file.
00001 /* ---------------------------------------------------------------------------- */
00002 /*                  Atmel Microcontroller Software Support                      */
00003 /*                       SAM Software Package License                           */
00004 /* ---------------------------------------------------------------------------- */
00005 /* Copyright (c) 2015, Atmel Corporation                                        */
00006 /*                                                                              */
00007 /* All rights reserved.                                                         */
00008 /*                                                                              */
00009 /* Redistribution and use in source and binary forms, with or without           */
00010 /* modification, are permitted provided that the following condition is met:    */
00011 /*                                                                              */
00012 /* - Redistributions of source code must retain the above copyright notice,     */
00013 /* this list of conditions and the disclaimer below.                            */
00014 /*                                                                              */
00015 /* Atmel's name may not be used to endorse or promote products derived from     */
00016 /* this software without specific prior written permission.                     */
00017 /*                                                                              */
00018 /* DISCLAIMER:  THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR   */
00019 /* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF */
00020 /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE   */
00021 /* DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,      */
00022 /* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT */
00023 /* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,  */
00024 /* OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF    */
00025 /* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING         */
00026 /* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, */
00027 /* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                           */
00028 /* ---------------------------------------------------------------------------- */
00029 
00030 /**
00031  * \file
00032  *
00033  * \section Purpose
00034  *
00035  *    Definition of a USB Audio Speakerphone Driver with two playback channels
00036  *    and one record channel.
00037  *
00038  * \section Usage
00039  *
00040  *    -# Enable and setup USB related pins (see pio & board.h).
00041  *    -# Implement a descriptor list using definitions
00042  *       - \ref usbd_audio_speakerphone_channel_num
00043  *       - \ref usbd_audio_speaker_interface_ids
00044  *       - \ref usbd_audio_speaker_entity_ids
00045  *    -# Configure the USB Audio Speakerphone driver using
00046  *       AUDDSpeakerPhoneDriver_Initialize
00047  *    -# To get %audio stream frames from host, use
00048  *       AUDDSpeakerPhoneDriver_Read
00049  *    -# To send %audio sampling stream to host, use
00050  *       AUDDSpeakerPhoneDriver_Write
00051  *
00052  */
00053 
00054 #ifndef AUDDSpeakerPhoneDriver_H
00055 #define AUDDSpeakerPhoneDriver_H
00056 
00057 /** \addtogroup usbd_audio_speakerphone
00058  *@{
00059  */
00060 
00061 /*------------------------------------------------------------------------------
00062  *         Headers
00063  *------------------------------------------------------------------------------*/
00064 
00065 #include <USBRequests.h>
00066 #include <USBDescriptors.h>
00067 #include <AUDDescriptors.h>
00068 
00069 #include "USBD.h"
00070 #include <USBD_HAL.h>
00071 #include <USBDDriver.h>
00072 
00073 /*------------------------------------------------------------------------------
00074  *         Definitions
00075  *------------------------------------------------------------------------------*/
00076 
00077 /** \addtogroup usbd_audio_speakerphone_channel_num Audio SpeakerPhone Channel Numbers
00078  *      @{
00079  * This page lists codes for USB Audio Speakerphone channel numbers.
00080  *
00081  * \section Playback channel numbers
00082  * - AUDDSpeakerPhoneDriver_MASTERCHANNEL
00083  * - AUDDSpeakerPhoneDriver_LEFTCHANNEL
00084  * - AUDDSpeakerPhoneDriver_RIGHTCHANNEL
00085  *
00086  * \section Record channel number
00087  * - AUDDSpeakerPhoneDriver_RECCHANNEL
00088  */
00089 
00090 /** Master channel of playback. */
00091 #define AUDDSpeakerPhoneDriver_MASTERCHANNEL                0
00092 /** Front left channel of playback. */
00093 #define AUDDSpeakerPhoneDriver_LEFTCHANNEL                  1
00094 /** Front right channel of playback. */
00095 #define AUDDSpeakerPhoneDriver_RIGHTCHANNEL                 2
00096 /** Channel of record. */
00097 #define AUDDSpeakerPhoneDriver_RECCHANNEL                   0
00098 /**      @}*/
00099 
00100 /** \addtogroup usbd_audio_speaker_interface_ids Audio SpeakerPhone Interface IDs
00101  *      @{
00102  * This page lists the interface numbers for USB Audio Speakerphone device.
00103  *
00104  * \section Interfaces
00105  * - AUDDSpeakerPhoneDriverDescriptors_CONTROL
00106  * - AUDDSpeakerPhoneDriverDescriptors_STREAMING
00107  * - AUDDSpeakerPhoneDriverDescriptors_STREAMINGIN
00108  */
00109 
00110 /** Audio control interface ID */
00111 #define AUDDSpeakerPhoneDriverDescriptors_CONTROL            0
00112 /** Audio streaming interface ID (OUT, for playback) */
00113 #define AUDDSpeakerPhoneDriverDescriptors_STREAMING          1
00114 /** Audio streaming interface ID (IN, for record) */
00115 #define AUDDSpeakerPhoneDriverDescriptors_STREAMINGIN        2
00116 /**      @}*/
00117 
00118 /** \addtogroup usbd_audio_speaker_entity_ids Audio SpeakerPhone Entity IDs
00119  *      @{
00120  * This page lists the entity IDs for USB Audio Speaker device.
00121  *
00122  * \section Entities
00123  * - AUDDSpeakerPhoneDriverDescriptors_INPUTTERMINAL
00124  * - AUDDSpeakerPhoneDriverDescriptors_OUTPUTTERMINAL
00125  * - AUDDSpeakerPhoneDriverDescriptors_FEATUREUNIT
00126  * - AUDDSpeakerPhoneDriverDescriptors_INPUTTERMINAL_REC
00127  * - AUDDSpeakerPhoneDriverDescriptors_OUTPUTTERMINAL_REC
00128  * - AUDDSpeakerPhoneDriverDescriptors_FEATUREUNIT_REC
00129  */
00130 
00131 /** Playback input terminal ID */
00132 #define AUDDSpeakerPhoneDriverDescriptors_INPUTTERMINAL      0
00133 /** Playback output terminal ID */
00134 #define AUDDSpeakerPhoneDriverDescriptors_OUTPUTTERMINAL     1
00135 /** Playback feature unit ID */
00136 #define AUDDSpeakerPhoneDriverDescriptors_FEATUREUNIT        2
00137 /** Record input terminal ID */
00138 #define AUDDSpeakerPhoneDriverDescriptors_INPUTTERMINAL_REC  3
00139 /** Record output terminal ID */
00140 #define AUDDSpeakerPhoneDriverDescriptors_OUTPUTTERMINAL_REC 4
00141 /** Record feature unit ID */
00142 #define AUDDSpeakerPhoneDriverDescriptors_FEATUREUNIT_REC    5
00143 /**      @}*/
00144 
00145 /*------------------------------------------------------------------------------
00146  *         Types
00147  *------------------------------------------------------------------------------*/
00148 
00149 /*------------------------------------------------------------------------------
00150  *  Audio control header descriptor with one slave interface.
00151  *------------------------------------------------------------------------------*/
00152 #pragma pack(1)
00153 #if defined   ( __CC_ARM   ) /* Keil ¦̀Vision 4 */
00154 #elif defined ( __ICCARM__ ) /* IAR Ewarm */
00155 #define __attribute__(...)
00156 #define __packed__  packed
00157 #elif defined (  __GNUC__  ) /* GCC CS3 */
00158 #define __packed__  aligned(1)
00159 #endif
00160 
00161 /**
00162  * \typedef AUDHeaderDescriptor2
00163  * \brief Header descriptor with 1 interface.
00164  */
00165 typedef struct _AUDHeaderDescriptor2 {
00166 
00167     /** Header descriptor. */
00168     AUDHeaderDescriptor header;
00169     /** Id of the first grouped interface - Speaker. */
00170     unsigned char bInterface0;
00171     /** Id of the second grouped interface - Speakerphone. */
00172     unsigned char bInterface1;
00173 
00174 } __attribute__ ((__packed__)) AUDHeaderDescriptor2; /* GCC */
00175 
00176 /**
00177  * \typedef AUDFeatureUnitDescriptor3
00178  * \brief Feature unit descriptor with 3 channel controls (master, right, left).
00179  */
00180 typedef struct _AUDFeatureUnitDescriptor3 {
00181 
00182     /** Feature unit descriptor. */
00183     AUDFeatureUnitDescriptor feature;
00184     /** Available controls for each channel. */
00185     unsigned char bmaControls[3];
00186     /** Index of a string descriptor for the feature unit. */
00187     unsigned char iFeature;
00188 
00189 } __attribute__ ((__packed__)) AUDFeatureUnitDescriptor3; /* GCC */
00190 
00191 /**
00192  * \typedef AUDDSpeakerPhoneDriverAudioControlDescriptors
00193  * \brief List of descriptors for detailing the audio control interface of a
00194  *        device using a USB Audio Speakerphoneer driver.
00195  */
00196 typedef struct _AUDDSpeakerPhoneDriverAudioControlDescriptors {
00197 
00198     /** Header descriptor (with one slave interface). */
00199     AUDHeaderDescriptor2 header;
00200     /** Input terminal descriptor. */
00201     AUDInputTerminalDescriptor inputSpeakerPhone;
00202     /** Output terminal descriptor. */
00203     AUDOutputTerminalDescriptor outputSpeakerPhone;
00204     /** Feature unit descriptor - SpeakerPhone. */
00205     AUDFeatureUnitDescriptor3 featureSpeakerPhone;
00206     /** Input terminal descriptor. */
00207     AUDInputTerminalDescriptor inputRec;
00208     /** Output terminal descriptor. */
00209     AUDOutputTerminalDescriptor outputRec;
00210     /** Feature unit descriptor - SpeakerPhonephone. */
00211     AUDFeatureUnitDescriptor3 featureRec;
00212 
00213 } __attribute__ ((__packed__)) AUDDSpeakerPhoneDriverAudioControlDescriptors; /* GCC */
00214 
00215 /**
00216  * \typedef AUDFormatTypeOneDescriptor1
00217  * \brief Format type I descriptor with one discrete sampling frequency.
00218  */
00219 typedef struct _AUDFormatTypeOneDescriptor1 {
00220 
00221     /** Format type I descriptor. */
00222     AUDFormatTypeOneDescriptor formatType;
00223     /** Sampling frequency in Hz. */
00224     unsigned char tSamFreq[3];
00225 
00226 } __attribute__ ((__packed__)) AUDFormatTypeOneDescriptor1; /* GCC */
00227 
00228 /**
00229  * \typedef AUDDSpeakerPhoneDriverConfigurationDescriptors
00230  * \brief Holds a list of descriptors returned as part of the configuration of
00231  *        a USB Audio Speakerphone device.
00232  */
00233 typedef struct _AUDDSpeakerPhoneDriverConfigurationDescriptors {
00234 
00235     /** Standard configuration. */
00236     USBConfigurationDescriptor configuration;
00237     /** Audio control interface. */
00238     USBInterfaceDescriptor control;
00239     /** Descriptors for the audio control interface. */
00240     AUDDSpeakerPhoneDriverAudioControlDescriptors controlDescriptors;
00241     /*- AUDIO OUT */
00242     /** Streaming out interface descriptor (with no endpoint, required). */
00243     USBInterfaceDescriptor streamingOutNoIsochronous;
00244     /** Streaming out interface descriptor. */
00245     USBInterfaceDescriptor streamingOut;
00246     /** Audio class descriptor for the streaming out interface. */
00247     AUDStreamingInterfaceDescriptor streamingOutClass;
00248     /** Stream format descriptor. */
00249     AUDFormatTypeOneDescriptor1 streamingOutFormatType;
00250     /** Streaming out endpoint descriptor. */
00251     AUDEndpointDescriptor streamingOutEndpoint;
00252     /** Audio class descriptor for the streaming out endpoint. */
00253     AUDDataEndpointDescriptor streamingOutDataEndpoint;
00254     /*- AUDIO IN */
00255     /** Streaming in interface descriptor (with no endpoint, required). */
00256     USBInterfaceDescriptor streamingInNoIsochronous;
00257     /** Streaming in interface descriptor. */
00258     USBInterfaceDescriptor streamingIn;
00259     /** Audio class descriptor for the streaming in interface. */
00260     AUDStreamingInterfaceDescriptor streamingInClass;
00261     /** Stream format descriptor. */
00262     AUDFormatTypeOneDescriptor1 streamingInFormatType;
00263     /** Streaming in endpoint descriptor. */
00264     AUDEndpointDescriptor streamingInEndpoint;
00265     /** Audio class descriptor for the streaming in endpoint. */
00266     AUDDataEndpointDescriptor streamingInDataEndpoint;
00267 
00268 } __attribute__ ((__packed__)) AUDDSpeakerPhoneDriverConfigurationDescriptors; /* GCC */
00269 
00270 #pragma pack()
00271 
00272 /*------------------------------------------------------------------------------
00273  *         Exported functions
00274  *------------------------------------------------------------------------------*/
00275 
00276 extern void AUDDSpeakerPhoneDriver_Initialize(
00277     const USBDDriverDescriptors *pDescriptors);
00278 
00279 extern void AUDDSpeakerPhoneDriver_ConfigurationChangeHandler(uint8_t cfgnum);
00280 
00281 extern void AUDDSpeakerPhoneDriver_InterfaceSettingChangedHandler(
00282     uint8_t interface,
00283     uint8_t setting);
00284 
00285 extern void AUDDSpeakerPhoneDriver_RequestHandler(
00286     const USBGenericRequest *request);
00287 
00288 extern uint8_t AUDDSpeakerPhoneDriver_Read(void *buffer,
00289                                            uint32_t length,
00290                                            TransferCallback callback,
00291                                            void *argument);
00292 
00293 extern uint8_t AUDDSpeakerPhoneDriver_SetupWrite(void * pListInit,
00294                                                  void * pDmaInit,
00295                                                  uint16_t listSize,
00296                                                  uint16_t delaySize,
00297                                                  TransferCallback callback,
00298                                                  void * argument);
00299 
00300 extern uint8_t AUDDSpeakerPhoneDriver_Write(void * buffer,uint16_t length);
00301 
00302 
00303 extern void AUDDSpeakerPhoneDriver_MuteChanged(uint8_t mic,
00304                                                     uint8_t channel,
00305                                                     uint8_t muted);
00306 
00307 extern void AUDDSpeakerPhoneDriver_StreamSettingChanged(uint8_t mic,
00308                                                             uint8_t newSetting);
00309 
00310 /**@}*/
00311 
00312 #endif /*#ifndef AUDDSpeakerPhoneDriver_H */
00313 
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines