LCOV - code coverage report
Current view: top level - zephyr/usb/class - usb_audio.h Coverage Total Hit
Test: new.info Lines: 76.0 % 25 19
Test Date: 2025-09-05 16:43:28

            Line data    Source code
       1            1 : /*
       2              :  * USB audio class core header
       3              :  *
       4              :  * Copyright (c) 2020 Nordic Semiconductor ASA
       5              :  *
       6              :  * SPDX-License-Identifier: Apache-2.0
       7              :  */
       8              : 
       9              : /**
      10              :  * @file
      11              :  * @brief USB Audio Device Class public header
      12              :  *
      13              :  * Header follows below documentation:
      14              :  * - USB Device Class Definition for Audio Devices (audio10.pdf)
      15              :  *
      16              :  * Additional documentation considered a part of USB Audio v1.0:
      17              :  * - USB Device Class Definition for Audio Data Formats (frmts10.pdf)
      18              :  * - USB Device Class Definition for Terminal Types (termt10.pdf)
      19              :  */
      20              : 
      21              : #ifndef ZEPHYR_INCLUDE_USB_CLASS_AUDIO_H_
      22              : #define ZEPHYR_INCLUDE_USB_CLASS_AUDIO_H_
      23              : 
      24              : #include <zephyr/usb/usb_ch9.h>
      25              : #include <zephyr/device.h>
      26              : #include <zephyr/net_buf.h>
      27              : #include <zephyr/sys/util.h>
      28              : 
      29              : /** Audio Interface Subclass Codes.
      30              :  * Refer to Table A-2 from audio10.pdf
      31              :  */
      32            0 : enum usb_audio_int_subclass_codes {
      33              :         USB_AUDIO_SUBCLASS_UNDEFINED    = 0x00,
      34              :         USB_AUDIO_AUDIOCONTROL          = 0x01,
      35              :         USB_AUDIO_AUDIOSTREAMING        = 0x02,
      36              :         USB_AUDIO_MIDISTREAMING         = 0x03
      37              : };
      38              : 
      39              : /** Audio Class-Specific AC Interface Descriptor Subtypes.
      40              :  * Refer to Table A-5 from audio10.pdf
      41              :  */
      42            0 : enum usb_audio_cs_ac_int_desc_subtypes {
      43              :         USB_AUDIO_AC_DESCRIPTOR_UNDEFINED       = 0x00,
      44              :         USB_AUDIO_HEADER                        = 0x01,
      45              :         USB_AUDIO_INPUT_TERMINAL                = 0x02,
      46              :         USB_AUDIO_OUTPUT_TERMINAL               = 0x03,
      47              :         USB_AUDIO_MIXER_UNIT                    = 0x04,
      48              :         USB_AUDIO_SELECTOR_UNIT                 = 0x05,
      49              :         USB_AUDIO_FEATURE_UNIT                  = 0x06,
      50              :         USB_AUDIO_PROCESSING_UNIT               = 0x07,
      51              :         USB_AUDIO_EXTENSION_UNIT                = 0x08
      52              : };
      53              : 
      54              : /** Audio Class-Specific AS Interface Descriptor Subtypes
      55              :  * Refer to Table A-6 from audio10.pdf
      56              :  */
      57            0 : enum usb_audio_cs_as_int_desc_subtypes {
      58              :         USB_AUDIO_AS_DESCRIPTOR_UNDEFINED       = 0x00,
      59              :         USB_AUDIO_AS_GENERAL                    = 0x01,
      60              :         USB_AUDIO_FORMAT_TYPE                   = 0x02,
      61              :         USB_AUDIO_FORMAT_SPECIFIC               = 0x03
      62              : };
      63              : 
      64              : /** Audio Class-Specific Request Codes
      65              :  * Refer to Table A-9 from audio10.pdf
      66              :  */
      67            0 : enum usb_audio_cs_req_codes {
      68              :         USB_AUDIO_REQUEST_CODE_UNDEFINED        = 0x00,
      69              :         USB_AUDIO_SET_CUR                       = 0x01,
      70              :         USB_AUDIO_GET_CUR                       = 0x81,
      71              :         USB_AUDIO_SET_MIN                       = 0x02,
      72              :         USB_AUDIO_GET_MIN                       = 0x82,
      73              :         USB_AUDIO_SET_MAX                       = 0x03,
      74              :         USB_AUDIO_GET_MAX                       = 0x83,
      75              :         USB_AUDIO_SET_RES                       = 0x04,
      76              :         USB_AUDIO_GET_RES                       = 0x84,
      77              :         USB_AUDIO_SET_MEM                       = 0x05,
      78              :         USB_AUDIO_GET_MEM                       = 0x85,
      79              :         USB_AUDIO_GET_STAT                      = 0xFF
      80              : };
      81              : 
      82              : /** Feature Unit Control Selectors
      83              :  * Refer to Table A-11 from audio10.pdf
      84              :  */
      85            0 : enum usb_audio_fucs {
      86              :         USB_AUDIO_FU_CONTROL_UNDEFINED          = 0x00,
      87              :         USB_AUDIO_FU_MUTE_CONTROL               = 0x01,
      88              :         USB_AUDIO_FU_VOLUME_CONTROL             = 0x02,
      89              :         USB_AUDIO_FU_BASS_CONTROL               = 0x03,
      90              :         USB_AUDIO_FU_MID_CONTROL                = 0x04,
      91              :         USB_AUDIO_FU_TREBLE_CONTROL             = 0x05,
      92              :         USB_AUDIO_FU_GRAPHIC_EQUALIZER_CONTROL  = 0x06,
      93              :         USB_AUDIO_FU_AUTOMATIC_GAIN_CONTROL     = 0x07,
      94              :         USB_AUDIO_FU_DELAY_CONTROL              = 0x08,
      95              :         USB_AUDIO_FU_BASS_BOOST_CONTROL         = 0x09,
      96              :         USB_AUDIO_FU_LOUDNESS_CONTROL           = 0x0A
      97              : };
      98              : 
      99              : /** USB Terminal Types
     100              :  * Refer to Table 2-1 - Table 2-4 from termt10.pdf
     101              :  */
     102            1 : enum usb_audio_terminal_types {
     103              :         /**
     104              :          * @name USB Terminal Types
     105              :          * @{
     106              :          */
     107              :         /** USB undefined */
     108              :         USB_AUDIO_USB_UNDEFINED   = 0x0100,
     109              :         /** USB streaming */
     110              :         USB_AUDIO_USB_STREAMING   = 0x0101,
     111              :         /** USB vendor specific */
     112              :         USB_AUDIO_USB_VENDOR_SPEC = 0x01FF,
     113              :         /** @} */
     114              : 
     115              :         /**
     116              :          * @name Input Terminal Types
     117              :          * @{
     118              :          */
     119              :         /** Input undefined */
     120              :         USB_AUDIO_IN_UNDEFINED      = 0x0200,
     121              :         /** Microphone */
     122              :         USB_AUDIO_IN_MICROPHONE     = 0x0201,
     123              :         /** Desktop microphone */
     124              :         USB_AUDIO_IN_DESKTOP_MIC    = 0x0202,
     125              :         /** Personal microphone */
     126              :         USB_AUDIO_IN_PERSONAL_MIC   = 0x0203,
     127              :         /** Omni directional microphone */
     128              :         USB_AUDIO_IN_OM_DIR_MIC     = 0x0204,
     129              :         /** Microphone array */
     130              :         USB_AUDIO_IN_MIC_ARRAY      = 0x0205,
     131              :         /** Processing microphone array */
     132              :         USB_AUDIO_IN_PROC_MIC_ARRAY = 0x0205,
     133              :         /** @} */
     134              : 
     135              :         /**
     136              :          * @name Output Terminal Types
     137              :          * @{
     138              :          */
     139              :         /** Output undefined */
     140              :         USB_AUDIO_OUT_UNDEFINED         = 0x0300,
     141              :         /** Speaker */
     142              :         USB_AUDIO_OUT_SPEAKER           = 0x0301,
     143              :         /** Headphones */
     144              :         USB_AUDIO_OUT_HEADPHONES        = 0x0302,
     145              :         /** Head mounted display audio */
     146              :         USB_AUDIO_OUT_HEAD_AUDIO        = 0x0303,
     147              :         /** Desktop speaker */
     148              :         USB_AUDIO_OUT_DESKTOP_SPEAKER   = 0x0304,
     149              :         /** Room speaker */
     150              :         USB_AUDIO_OUT_ROOM_SPEAKER      = 0x0305,
     151              :         /** Communication speaker */
     152              :         USB_AUDIO_OUT_COMM_SPEAKER      = 0x0306,
     153              :         /** Low frequency effects speaker */
     154              :         USB_AUDIO_OUT_LOW_FREQ_SPEAKER  = 0x0307,
     155              :         /** @} */
     156              : 
     157              :         /**
     158              :          * @name Bi-directional Terminal Types
     159              :          * @{
     160              :          */
     161              :         /** Bidirectional undefined */
     162              :         USB_AUDIO_IO_UNDEFINED                  = 0x0400,
     163              :         /** Handset */
     164              :         USB_AUDIO_IO_HANDSET                    = 0x0401,
     165              :         /** Headset */
     166              :         USB_AUDIO_IO_HEADSET                    = 0x0402,
     167              :         /** Speakerphone, no echo reduction */
     168              :         USB_AUDIO_IO_SPEAKERPHONE_ECHO_NONE     = 0x0403,
     169              :         /** Speakerphone, echo reduction */
     170              :         USB_AUDIO_IO_SPEAKERPHONE_ECHO_SUP      = 0x0404,
     171              :         /** Speakerphone, echo cancellation */
     172              :         USB_AUDIO_IO_SPEAKERPHONE_ECHO_CAN      = 0x0405,
     173              : };
     174              : 
     175              : /**
     176              :  * @brief Audio device direction.
     177              :  */
     178            0 : enum usb_audio_direction {
     179              :         USB_AUDIO_IN = 0x00,
     180              :         USB_AUDIO_OUT = 0x01
     181              : };
     182              : 
     183              : /**
     184              :  * @brief Feature Unit event structure.
     185              :  *
     186              :  * The event structure is used by feature_update_cb in order to inform the App
     187              :  * whenever the Host has modified one of the device features.
     188              :  */
     189            1 : struct usb_audio_fu_evt {
     190              :         /**
     191              :          * The device direction that has been changed.
     192              :          * Applicable for Headset device only.
     193              :          */
     194            1 :         enum usb_audio_direction dir;
     195              :         /** Control selector feature that has been changed. */
     196            1 :         enum usb_audio_fucs cs;
     197              :         /**
     198              :          * Device channel that has been changed.
     199              :          * If 0xFF, then all channels have been changed.
     200              :          */
     201            1 :         uint8_t channel;
     202              :         /** Length of the val field. */
     203            1 :         uint8_t val_len;
     204              :         /** Value of the feature that has been set. */
     205            1 :         const void *val;
     206              : };
     207              : 
     208              : /**
     209              :  * @brief Callback type used to inform the app that data were requested
     210              :  *        from the device and may be send to the Host.
     211              :  *        For sending the data usb_audio_send() API function should be used.
     212              :  *
     213              :  * @note User may not use this callback and may try to send in 1ms task
     214              :  *       instead. Sending every 1ms may be unsuccessful and may return -EAGAIN
     215              :  *       if Host did not required data.
     216              :  *
     217              :  * @param dev The device for which data were requested by the Host.
     218              :  */
     219            1 : typedef void (*usb_audio_data_request_cb_t)(const struct device *dev);
     220              : 
     221              : /**
     222              :  * @brief Callback type used to inform the app that data were successfully
     223              :  *        send/received.
     224              :  *
     225              :  * @param dev    The device for which the callback was called.
     226              :  * @param buffer Pointer to the net_buf data chunk that was successfully
     227              :  *               send/received. If the application uses data_written_cb and/or
     228              :  *               data_received_cb callbacks it is responsible for freeing the
     229              :  *               buffer by itself.
     230              :  * @param size   Amount of data that were successfully send/received.
     231              :  */
     232            1 : typedef void (*usb_audio_data_completion_cb_t)(const struct device *dev,
     233              :                                                struct net_buf *buffer,
     234              :                                                size_t size);
     235              : 
     236              : /**
     237              :  * @brief Callback type used to inform the app that Host has changed
     238              :  *        one of the features configured for the device.
     239              :  *        Applicable for all devices.
     240              :  *
     241              :  * @warning Host may not use all of configured features.
     242              :  *
     243              :  * @param dev USB Audio device
     244              :  * @param evt Pointer to an event to be parsed by the App.
     245              :  *            Pointer struct is temporary and is valid only during the
     246              :  *            execution of this callback.
     247              :  */
     248            1 : typedef void (*usb_audio_feature_updated_cb_t)(const struct device *dev,
     249              :                                                const struct usb_audio_fu_evt *evt);
     250              : 
     251              : /**
     252              :  * @brief Audio callbacks used to interact with audio devices by user App.
     253              :  *
     254              :  * usb_audio_ops structure contains all relevant callbacks to interact with
     255              :  * USB Audio devices. Each of this callbacks is optional and may be left NULL.
     256              :  * This will not break the stack but could make USB Audio device useless.
     257              :  * Depending on the device some of those callbacks are necessary to make USB
     258              :  * device work as expected sending/receiving data. For more information refer
     259              :  * to callback documentation above.
     260              :  */
     261            1 : struct usb_audio_ops {
     262              :         /** Callback called when data could be send */
     263            1 :         usb_audio_data_request_cb_t data_request_cb;
     264              : 
     265              :         /** Callback called when data were successfully written with sending
     266              :          * capable device. Applicable for headset and microphone. Unused for
     267              :          * headphones.
     268              :          */
     269            1 :         usb_audio_data_completion_cb_t data_written_cb;
     270              : 
     271              :         /** Callback called when data were successfully received by receive
     272              :          * capable device. Applicable for headset and headphones. Unused for
     273              :          * microphone.
     274              :          */
     275            1 :         usb_audio_data_completion_cb_t data_received_cb;
     276              : 
     277              :         /** Callback called when features were modified by the Host */
     278            1 :         usb_audio_feature_updated_cb_t feature_update_cb;
     279              : };
     280              : 
     281              : /** @brief Get the frame size that is accepted by the Host.
     282              :  *
     283              :  * @deprecated Use @ref uac2_device instead.
     284              :  *
     285              :  * This function returns the frame size for Input Devices that is expected
     286              :  * by the Host. Returned value rely on Input Device configuration:
     287              :  * - number of channels
     288              :  * - sampling frequency
     289              :  * - sample resolution
     290              :  * Device configuration is done via DT overlay.
     291              :  *
     292              :  * @param dev The Input device that is asked for frame size.
     293              :  *
     294              :  * @warning Do not use with OUT only devices (Headphones).
     295              :  *          For OUT only devices this function shall return 0.
     296              :  */
     297            1 : __deprecated size_t usb_audio_get_in_frame_size(const struct device *dev);
     298              : 
     299              : /**
     300              :  * @brief Register the USB Audio device and make it usable.
     301              :  *        This must be called in order to make the device work
     302              :  *        and respond to all relevant requests.
     303              :  *
     304              :  * @deprecated Use @ref uac2_device instead.
     305              :  *
     306              :  * @param dev USB Audio device
     307              :  * @param ops USB audio callback structure. Callback are used to
     308              :  *            inform the user about what is happening
     309              :  */
     310            1 : __deprecated void usb_audio_register(const struct device *dev,
     311              :                         const struct usb_audio_ops *ops);
     312              : 
     313              : /**
     314              :  * @brief Send data using USB Audio device
     315              :  *
     316              :  * @deprecated Use @ref uac2_device instead.
     317              :  *
     318              :  * @param dev    USB Audio device which will send the data
     319              :  *               over its ISO IN endpoint
     320              :  * @param buffer Pointer to the buffer that should be send. User is
     321              :  *               responsible for managing the buffer for Input devices. In case
     322              :  *               of sending error user must decide if the buffer should be
     323              :  *               dropped or retransmitted.
     324              :  *               After the buffer was sent successfully it is passed to the
     325              :  *               data_written_cb callback if the application uses one or
     326              :  *               automatically freed otherwise.
     327              :  *               User must provide proper net_buf chunk especially when
     328              :  *               it comes to its size. This information can be obtained
     329              :  *               using usb_audio_get_in_frame_size() API function.
     330              :  *
     331              :  * @param len    Length of the data to be send
     332              :  *
     333              :  * @return 0 on success, negative error on fail
     334              :  */
     335            1 : __deprecated int usb_audio_send(const struct device *dev, struct net_buf *buffer,
     336              :                    size_t len);
     337              : 
     338              : #endif /* ZEPHYR_INCLUDE_USB_CLASS_AUDIO_H_ */
        

Generated by: LCOV version 2.0-1