system/dev/audio/usb-audio/usb-audio-units.h - zircon/ - Git at Google

 // Copyright 2018 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 #pragma once

 #include <fbl/array.h>
 #include <fbl/intrusive_wavl_tree.h>
 #include <fbl/macros.h>
 #include <fbl/ref_counted.h>
 #include <fbl/ref_ptr.h>
 #include <zircon/hw/usb/audio.h>

 #include <utility>

 #include "usb-audio-descriptors.h"

 // Notes: usb-audio-units.h contains a collection of definitions of classes used
 // when building the graph of Terminals/Units which make up the inside of a USB
 // Audio Control interface.

 namespace audio {
 namespace usb {

 class AudioUnit : public fbl::WAVLTreeContainable<fbl::RefPtr<AudioUnit>>,
                   public fbl::RefCounted<AudioUnit> {
   public:
     static constexpr uint32_t kInvalidID = 0xFFFFFFFF;

     enum class Type : uint8_t {
         InputTerminal  = USB_AUDIO_AC_INPUT_TERMINAL,
         OutputTerminal = USB_AUDIO_AC_OUTPUT_TERMINAL,
         MixerUnit      = USB_AUDIO_AC_MIXER_UNIT,
         SelectorUnit   = USB_AUDIO_AC_SELECTOR_UNIT,
         FeatureUnit    = USB_AUDIO_AC_FEATURE_UNIT,
         ProcessingUnit = USB_AUDIO_AC_PROCESSING_UNIT,
         ExtensionUnit  = USB_AUDIO_AC_EXTENSION_UNIT,
     };

     static fbl::RefPtr<AudioUnit> Create(const DescriptorListMemory::Iterator& iter, uint8_t iid);

     Type type() const { return static_cast<Type>(desc_->bDescriptorSubtype); }
     const char* type_name() const;
     uint8_t iid() const { return iid_; }
     uint32_t id() const { return desc_->bID; }
     uint32_t GetKey() const { return id(); }

     // the 16 bit index which needs to be used any time a command needs to be
     // sent to this unit (the wIndex field).  This is formed from the unit ID
     // (high byte) and the control interface id (low byte).
     uint16_t index() const { return static_cast<uint16_t>((id() << 8) | iid()); }

     // Every audio unit needs to define which source(s) feed it.  This
     // information is contained in the unit/terminal's descriptors, but where it
     // lives (and whether or not it is simply implied, such as in the case of an
     // InputTerminal) depends entirely on the type of unit/terminal in question.
     // Because of this, we simply model the interface using pure virtual
     // methods.
     virtual uint32_t source_count() const = 0;
     virtual uint32_t source_id(uint32_t ndx) const = 0;

     // A hook which allows certain audio units/terminals to read their
     // capabilities at startup.  Not all of the units need to do this, so the
     // default hook implementation is a no-op.
     virtual zx_status_t Probe(const usb_protocol_t& proto) { return ZX_OK; }

     // A state flag used by the audio control interface class when it is
     // searching the terminal/unit graph for audio paths to publish.
     bool& visited() { return visited_; }

     // A flag indicating whether or not there is at least one audio path in the
     // system attempting to use this unit/terminal
     bool in_use() const { return in_use_; }
     void set_in_use() { in_use_ = true; }

   protected:
     friend class fbl::RefPtr<AudioUnit>;

     AudioUnit(fbl::RefPtr<DescriptorListMemory> desc_list,
               const usb_audio_ac_ut_desc* desc,
               uint8_t iid)
         : desc_list_(std::move(desc_list)), desc_(desc), iid_(iid) {}
     virtual ~AudioUnit() {}

     DISALLOW_COPY_ASSIGN_AND_MOVE(AudioUnit);

     template <typename T>
     zx_status_t CtrlReq(const usb_protocol_t& proto, uint8_t code, uint16_t val, T* data) {
         return CtrlReq(proto, code, val, sizeof(*data), data);
     }

     // See note in UsbAudioControlInterface.  Holding a constant RefPtr to our
     // descriptor list ensures that we can never accidentally release the list
     // while we still exist.
     const fbl::RefPtr<DescriptorListMemory> desc_list_;
     const usb_audio_ac_ut_desc* const desc_;

     // The interface id of the control interface that this unit/terminal belongs
     // to.  All units need to know this number in order to properly address
     // get/set commands.
     const uint8_t iid_;

 private:
     zx_status_t CtrlReq(const usb_protocol_t& proto,
                         uint8_t code, uint16_t val, uint16_t len, void* data);

     // State flags used when building valid audio paths.
     bool visited_ = false;
     bool in_use_ = false;
 };

 class Terminal : public AudioUnit {
   public:
     uint16_t terminal_type() const { return term_desc_->wTerminalType; }
     bool is_stream_terminal() const { return terminal_type() == USB_AUDIO_TERMINAL_USB_STREAMING; }
     bool is_usb_terminal() const {
         // See Universal Serial Bus Device Class Definition for Terminal Types,
         // rev 1.0 Section 2.1
         return (terminal_type() & 0xFF00) == 0x0100;
     }

   protected:
     Terminal(fbl::RefPtr<DescriptorListMemory> desc_list,
              const usb_audio_ac_terminal_desc* desc,
              uint8_t iid)
         : AudioUnit(std::move(desc_list), reinterpret_cast<const usb_audio_ac_ut_desc*>(desc), iid),
           term_desc_(desc) {}

     DISALLOW_COPY_ASSIGN_AND_MOVE(Terminal);

   private:
     const usb_audio_ac_terminal_desc* const term_desc_;
 };

 class InputTerminal : public Terminal {
   public:
     uint32_t source_count() const final { return 0; }
     uint32_t source_id(uint32_t ndx) const final { return kInvalidID; }

   private:
     friend class AudioUnit;

     static fbl::RefPtr<InputTerminal> Create(const DescriptorListMemory::Iterator& iter,
                                              uint8_t iid);

     InputTerminal(fbl::RefPtr<DescriptorListMemory> desc_list,
                   const usb_audio_ac_input_terminal_desc* desc,
                   uint8_t iid)
         : Terminal(std::move(desc_list),
                    reinterpret_cast<const usb_audio_ac_terminal_desc*>(desc),
                    iid) {}

     DISALLOW_COPY_ASSIGN_AND_MOVE(InputTerminal);

     const usb_audio_ac_input_terminal_desc* input_desc() const {
         return reinterpret_cast<const usb_audio_ac_input_terminal_desc*>(desc_);
     }
 };

 class OutputTerminal : public Terminal {
   public:
     uint32_t source_count() const final { return 1; }
     uint32_t source_id(uint32_t ndx) const final {
         return (ndx == 0) ? output_desc()->bSourceID : kInvalidID;
     }

   private:
     friend class AudioUnit;

     static fbl::RefPtr<OutputTerminal> Create(const DescriptorListMemory::Iterator& iter,
                                               uint8_t iid);

     OutputTerminal(fbl::RefPtr<DescriptorListMemory> desc_list,
                    const usb_audio_ac_output_terminal_desc* desc,
                    uint8_t iid)
         : Terminal(std::move(desc_list),
                    reinterpret_cast<const usb_audio_ac_terminal_desc*>(desc), iid) {}

     DISALLOW_COPY_ASSIGN_AND_MOVE(OutputTerminal);

     const usb_audio_ac_output_terminal_desc* output_desc() const {
         return reinterpret_cast<const usb_audio_ac_output_terminal_desc*>(desc_);
     }
 };

 class MixerUnit : public AudioUnit {
   public:
     uint32_t source_count() const final { return mixer_desc()->bNrInPins; }
     uint32_t source_id(uint32_t ndx) const final {
         return (ndx < source_count()) ? mixer_desc()->baSourceID[ndx] : kInvalidID;
     }

     const usb_audio_ac_mixer_unit_desc_0* mixer_desc() const {
         return reinterpret_cast<const usb_audio_ac_mixer_unit_desc_0*>(desc_);
     }
     const usb_audio_ac_mixer_unit_desc_1* mixer_desc_1() const { return mixer_desc_1_; }
     const usb_audio_ac_mixer_unit_desc_2* mixer_desc_2() const { return mixer_desc_2_; }

     // TODO(johngro): Add a probe method to mixer so that we can read all of the
     // mix/max/cur settings for the mixer crossbar.  Because of the way that we
     // are organizing our graph, this method may need to be extended to have
     // access to the set of all units present in the control interface.

   private:
     friend class AudioUnit;

     static fbl::RefPtr<MixerUnit> Create(const DescriptorListMemory::Iterator& iter, uint8_t iid);

     MixerUnit(fbl::RefPtr<DescriptorListMemory> desc_list,
               const usb_audio_ac_mixer_unit_desc_0* desc_0,
               const usb_audio_ac_mixer_unit_desc_1* desc_1,
               const usb_audio_ac_mixer_unit_desc_2* desc_2,
               uint8_t iid)
         : AudioUnit(std::move(desc_list),
                     reinterpret_cast<const usb_audio_ac_ut_desc*>(desc_0),
                     iid),
           mixer_desc_1_(desc_1),
           mixer_desc_2_(desc_2) {}

     DISALLOW_COPY_ASSIGN_AND_MOVE(MixerUnit);

     const usb_audio_ac_mixer_unit_desc_1* const mixer_desc_1_;
     const usb_audio_ac_mixer_unit_desc_2* const mixer_desc_2_;
 };

 class SelectorUnit : public AudioUnit {
   public:
     uint32_t source_count() const final { return selector_desc()->bNrInPins; }
     uint32_t source_id(uint32_t ndx) const final {
         return (ndx < source_count()) ? selector_desc()->baSourceID[ndx] : kInvalidID;
     }

     const usb_audio_ac_selector_unit_desc_0* selector_desc() const {
         return reinterpret_cast<const usb_audio_ac_selector_unit_desc_0*>(desc_);
     }

     const usb_audio_ac_selector_unit_desc_1* selector_desc_1() const { return selector_desc_1_; }

     // Select the input to the selector unit identified by the desired upstream
     // unit's id;
     zx_status_t Select(const usb_protocol_t& proto, uint8_t upstream_id);

   private:
     friend class AudioUnit;

     static fbl::RefPtr<SelectorUnit> Create(const DescriptorListMemory::Iterator& iter,
                                             uint8_t iid);

     SelectorUnit(fbl::RefPtr<DescriptorListMemory> desc_list,
                  const usb_audio_ac_selector_unit_desc_0* desc_0,
                  const usb_audio_ac_selector_unit_desc_1* desc_1,
                  uint8_t iid)
         : AudioUnit(std::move(desc_list),
                     reinterpret_cast<const usb_audio_ac_ut_desc*>(desc_0),
                     iid),
           selector_desc_1_(desc_1) {}

     DISALLOW_COPY_ASSIGN_AND_MOVE(SelectorUnit);

     const usb_audio_ac_selector_unit_desc_1* const selector_desc_1_;
 };

 class FeatureUnit : public AudioUnit {
   public:
     uint32_t source_count() const final { return 1; }
     uint32_t source_id(uint32_t ndx) const final { return feature_desc()->bSourceID; }

     bool has_vol()  const { return (master_feat_ | ch_feat_) & USB_AUDIO_FU_BMA_VOLUME; }
     bool has_agc()  const { return (master_feat_ | ch_feat_) & USB_AUDIO_FU_BMA_AUTOMATIC_GAIN; }
     bool has_mute() const { return (master_feat_ | ch_feat_) & USB_AUDIO_FU_BMA_MUTE; }

     float vol_min_db() const { return static_cast<float>(vol_min_) * kDbPerTick; }
     float vol_max_db() const { return static_cast<float>(vol_max_) * kDbPerTick; }
     float vol_res_db() const { return static_cast<float>(vol_res_) * kDbPerTick; }
     float vol_cur_db() const { return static_cast<float>(vol_cur_) * kDbPerTick; }
     bool  mute_cur()   const { return !!mute_cur_; }
     bool  agc_cur()    const { return !!agc_cur_; }

     const usb_audio_ac_feature_unit_desc_0* feature_desc() const {
         return reinterpret_cast<const usb_audio_ac_feature_unit_desc_0*>(desc_);
     }
     const usb_audio_ac_feature_unit_desc_1* feature_desc_1() const { return feature_desc_1_; }

     zx_status_t Probe(const usb_protocol_t& proto) final;

     // Do the best we can to set the volume/mute/agc.  Return the value actually set.
     float SetVol (const usb_protocol_t& proto, float db);
     bool  SetMute(const usb_protocol_t& proto, bool mute);
     bool  SetAgc (const usb_protocol_t& proto, bool enabled);

   private:
     friend class AudioUnit;

     // Section 5.2.2.4.3.2 of the USB Audio 1.0 spec
     static constexpr float kDbPerTick = 1.0f / 256.0f;

     // A small struct used to track the various features supported by a channel
     // controlled by this feature unit.
     struct Features {
         bool has_vol()  const { return supported_ & USB_AUDIO_FU_BMA_VOLUME; }
         bool has_mute() const { return supported_ & USB_AUDIO_FU_BMA_MUTE; }
         bool has_agc()  const { return supported_ & USB_AUDIO_FU_BMA_AUTOMATIC_GAIN; }

         uint32_t supported_ = 0;
         int16_t  vol_min_ = 0;
         int16_t  vol_max_ = 0;
         int16_t  vol_res_ = 0;
         int16_t  vol_cur_ = 0;
         bool     mute_cur = false;
     };

     static fbl::RefPtr<FeatureUnit> Create(const DescriptorListMemory::Iterator& iter, uint8_t iid);

     // Map a feature ordinal to its corresponding bit in the bmaControls
     // bitmask.  Thankfully, as of the USB Audio 1.0 spec, this is just a simple
     // offset and shift operation.
     static constexpr uint32_t FeatureToBit(uint8_t ord) { return 1u << (ord - 1); }

     FeatureUnit(fbl::RefPtr<DescriptorListMemory> desc_list,
                 const usb_audio_ac_feature_unit_desc_0* desc_0,
                 const usb_audio_ac_feature_unit_desc_1* desc_1,
                 fbl::unique_ptr<Features[]> feature_mem,
                 size_t feature_len,
                 uint8_t iid)
         : AudioUnit(std::move(desc_list),
                     reinterpret_cast<const usb_audio_ac_ut_desc*>(desc_0),
                     iid),
           feature_desc_1_(desc_1),
           features_(feature_mem.release(), feature_len) {}

     DISALLOW_COPY_ASSIGN_AND_MOVE(FeatureUnit);

     template <typename T>
     zx_status_t FeatCtrlReq(const usb_protocol_t& proto,
                             uint8_t code, uint8_t ctrl, uint8_t ch, T* data) {
         // See Section 5.2.2.4 in the USB Audio 1.0 spec for the encoding of val.
         uint16_t val = static_cast<uint16_t>((static_cast<uint16_t>(ctrl) << 8) | ch);
         return CtrlReq<T>(proto, code, val, data);
     }

     template <typename T>
     void SetFeature(const usb_protocol_t& proto, uint8_t feature, T val) {
         auto mask = FeatureToBit(feature);

         if (master_feat_ & mask) {
             FeatCtrlReq(proto, USB_AUDIO_SET_CUR, feature, 0, &val);
         } else {
             for (size_t i = 1; i < features_.size(); ++i) {
                 uint8_t ch = static_cast<uint8_t>(i);
                 FeatCtrlReq(proto, USB_AUDIO_SET_CUR, feature, ch, &val);
             }
         }
     }

     const usb_audio_ac_feature_unit_desc_1* const feature_desc_1_;
     const fbl::Array<Features> features_;

     uint32_t master_feat_ = 0;
     uint32_t ch_feat_ = 0;
     int16_t vol_min_ = 0;
     int16_t vol_max_ = 0;
     int16_t vol_res_ = 0;
     int16_t vol_cur_ = 0;
     uint8_t mute_cur_ = 0;
     uint8_t agc_cur_ = 0;
 };

 class ProcessingUnit : public AudioUnit {
   public:
     uint32_t source_count() const final { return processing_desc()->bNrInPins; }
     uint32_t source_id(uint32_t ndx) const final {
         return (ndx < source_count()) ? processing_desc()->baSourceID[ndx] : kInvalidID;
     }

     const usb_audio_ac_processing_unit_desc_0* processing_desc() const {
         return reinterpret_cast<const usb_audio_ac_processing_unit_desc_0*>(desc_);
     }

     const usb_audio_ac_processing_unit_desc_1* processing_desc_1() const {
         return processing_desc_1_;
     }

     const usb_audio_ac_processing_unit_desc_2* processing_desc_2() const {
         return processing_desc_2_;
     }

   private:
     friend class AudioUnit;

     static fbl::RefPtr<ProcessingUnit> Create(const DescriptorListMemory::Iterator& iter,
                                               uint8_t iid);

     ProcessingUnit(fbl::RefPtr<DescriptorListMemory> desc_list,
                    const usb_audio_ac_processing_unit_desc_0* desc_0,
                    const usb_audio_ac_processing_unit_desc_1* desc_1,
                    const usb_audio_ac_processing_unit_desc_2* desc_2,
                    uint8_t iid)
         : AudioUnit(std::move(desc_list),
                     reinterpret_cast<const usb_audio_ac_ut_desc*>(desc_0),
                     iid),
           processing_desc_1_(desc_1),
           processing_desc_2_(desc_2) {}

     DISALLOW_COPY_ASSIGN_AND_MOVE(ProcessingUnit);

     const usb_audio_ac_processing_unit_desc_1* const processing_desc_1_;
     const usb_audio_ac_processing_unit_desc_2* const processing_desc_2_;
 };

 class ExtensionUnit : public AudioUnit {
   public:
     uint32_t source_count() const final { return extension_desc()->bNrInPins; }
     uint32_t source_id(uint32_t ndx) const final {
         return (ndx < source_count()) ? extension_desc()->baSourceID[ndx] : kInvalidID;
     }

     const usb_audio_ac_extension_unit_desc_0* extension_desc() const {
         return reinterpret_cast<const usb_audio_ac_extension_unit_desc_0*>(desc_);
     }

     const usb_audio_ac_extension_unit_desc_1* extension_desc_1() const { return extension_desc_1_; }
     const usb_audio_ac_extension_unit_desc_2* extension_desc_2() const { return extension_desc_2_; }

   private:
     friend class AudioUnit;

     static fbl::RefPtr<ExtensionUnit> Create(const DescriptorListMemory::Iterator& iter,
                                              uint8_t iid);

     ExtensionUnit(fbl::RefPtr<DescriptorListMemory> desc_list,
               const usb_audio_ac_extension_unit_desc_0* desc_0,
               const usb_audio_ac_extension_unit_desc_1* desc_1,
               const usb_audio_ac_extension_unit_desc_2* desc_2,
               uint8_t iid)
         : AudioUnit(std::move(desc_list),
                     reinterpret_cast<const usb_audio_ac_ut_desc*>(desc_0),
                     iid),
           extension_desc_1_(desc_1),
           extension_desc_2_(desc_2) {}

     DISALLOW_COPY_ASSIGN_AND_MOVE(ExtensionUnit);

     const usb_audio_ac_extension_unit_desc_1* const extension_desc_1_;
     const usb_audio_ac_extension_unit_desc_2* const extension_desc_2_;
 };

 }  // namespace usb
 }  // namespace audio
	// Copyright 2018 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	#pragma once

	#include <fbl/array.h>
	#include <fbl/intrusive_wavl_tree.h>
	#include <fbl/macros.h>
	#include <fbl/ref_counted.h>
	#include <fbl/ref_ptr.h>
	#include <zircon/hw/usb/audio.h>

	#include <utility>

	#include "usb-audio-descriptors.h"

	// Notes: usb-audio-units.h contains a collection of definitions of classes used
	// when building the graph of Terminals/Units which make up the inside of a USB
	// Audio Control interface.

	namespace audio {
	namespace usb {

	class AudioUnit : public fbl::WAVLTreeContainable<fbl::RefPtr<AudioUnit>>,
	public fbl::RefCounted<AudioUnit> {
	public:
	static constexpr uint32_t kInvalidID = 0xFFFFFFFF;

	enum class Type : uint8_t {
	InputTerminal = USB_AUDIO_AC_INPUT_TERMINAL,
	OutputTerminal = USB_AUDIO_AC_OUTPUT_TERMINAL,
	MixerUnit = USB_AUDIO_AC_MIXER_UNIT,
	SelectorUnit = USB_AUDIO_AC_SELECTOR_UNIT,
	FeatureUnit = USB_AUDIO_AC_FEATURE_UNIT,
	ProcessingUnit = USB_AUDIO_AC_PROCESSING_UNIT,
	ExtensionUnit = USB_AUDIO_AC_EXTENSION_UNIT,
	};

	static fbl::RefPtr<AudioUnit> Create(const DescriptorListMemory::Iterator& iter, uint8_t iid);

	Type type() const { return static_cast<Type>(desc_->bDescriptorSubtype); }
	const char* type_name() const;
	uint8_t iid() const { return iid_; }
	uint32_t id() const { return desc_->bID; }
	uint32_t GetKey() const { return id(); }

	// the 16 bit index which needs to be used any time a command needs to be
	// sent to this unit (the wIndex field). This is formed from the unit ID
	// (high byte) and the control interface id (low byte).
	uint16_t index() const { return static_cast<uint16_t>((id() << 8) \| iid()); }

	// Every audio unit needs to define which source(s) feed it. This
	// information is contained in the unit/terminal's descriptors, but where it
	// lives (and whether or not it is simply implied, such as in the case of an
	// InputTerminal) depends entirely on the type of unit/terminal in question.
	// Because of this, we simply model the interface using pure virtual
	// methods.
	virtual uint32_t source_count() const = 0;
	virtual uint32_t source_id(uint32_t ndx) const = 0;

	// A hook which allows certain audio units/terminals to read their
	// capabilities at startup. Not all of the units need to do this, so the
	// default hook implementation is a no-op.
	virtual zx_status_t Probe(const usb_protocol_t& proto) { return ZX_OK; }

	// A state flag used by the audio control interface class when it is
	// searching the terminal/unit graph for audio paths to publish.
	bool& visited() { return visited_; }

	// A flag indicating whether or not there is at least one audio path in the
	// system attempting to use this unit/terminal
	bool in_use() const { return in_use_; }
	void set_in_use() { in_use_ = true; }

	protected:
	friend class fbl::RefPtr<AudioUnit>;

	AudioUnit(fbl::RefPtr<DescriptorListMemory> desc_list,
	const usb_audio_ac_ut_desc* desc,
	uint8_t iid)
	: desc_list_(std::move(desc_list)), desc_(desc), iid_(iid) {}
	virtual ~AudioUnit() {}

	DISALLOW_COPY_ASSIGN_AND_MOVE(AudioUnit);

	template <typename T>
	zx_status_t CtrlReq(const usb_protocol_t& proto, uint8_t code, uint16_t val, T* data) {
	return CtrlReq(proto, code, val, sizeof(*data), data);
	}

	// See note in UsbAudioControlInterface. Holding a constant RefPtr to our
	// descriptor list ensures that we can never accidentally release the list
	// while we still exist.
	const fbl::RefPtr<DescriptorListMemory> desc_list_;
	const usb_audio_ac_ut_desc* const desc_;

	// The interface id of the control interface that this unit/terminal belongs
	// to. All units need to know this number in order to properly address
	// get/set commands.
	const uint8_t iid_;

	private:
	zx_status_t CtrlReq(const usb_protocol_t& proto,
	uint8_t code, uint16_t val, uint16_t len, void* data);

	// State flags used when building valid audio paths.
	bool visited_ = false;
	bool in_use_ = false;
	};

	class Terminal : public AudioUnit {
	public:
	uint16_t terminal_type() const { return term_desc_->wTerminalType; }
	bool is_stream_terminal() const { return terminal_type() == USB_AUDIO_TERMINAL_USB_STREAMING; }
	bool is_usb_terminal() const {
	// See Universal Serial Bus Device Class Definition for Terminal Types,
	// rev 1.0 Section 2.1
	return (terminal_type() & 0xFF00) == 0x0100;
	}

	protected:
	Terminal(fbl::RefPtr<DescriptorListMemory> desc_list,
	const usb_audio_ac_terminal_desc* desc,
	uint8_t iid)
	: AudioUnit(std::move(desc_list), reinterpret_cast<const usb_audio_ac_ut_desc*>(desc), iid),
	term_desc_(desc) {}

	DISALLOW_COPY_ASSIGN_AND_MOVE(Terminal);

	private:
	const usb_audio_ac_terminal_desc* const term_desc_;
	};

	class InputTerminal : public Terminal {
	public:
	uint32_t source_count() const final { return 0; }
	uint32_t source_id(uint32_t ndx) const final { return kInvalidID; }

	private:
	friend class AudioUnit;

	static fbl::RefPtr<InputTerminal> Create(const DescriptorListMemory::Iterator& iter,
	uint8_t iid);

	InputTerminal(fbl::RefPtr<DescriptorListMemory> desc_list,
	const usb_audio_ac_input_terminal_desc* desc,
	uint8_t iid)
	: Terminal(std::move(desc_list),
	reinterpret_cast<const usb_audio_ac_terminal_desc*>(desc),
	iid) {}

	DISALLOW_COPY_ASSIGN_AND_MOVE(InputTerminal);

	const usb_audio_ac_input_terminal_desc* input_desc() const {
	return reinterpret_cast<const usb_audio_ac_input_terminal_desc*>(desc_);
	}
	};

	class OutputTerminal : public Terminal {
	public:
	uint32_t source_count() const final { return 1; }
	uint32_t source_id(uint32_t ndx) const final {
	return (ndx == 0) ? output_desc()->bSourceID : kInvalidID;
	}

	private:
	friend class AudioUnit;

	static fbl::RefPtr<OutputTerminal> Create(const DescriptorListMemory::Iterator& iter,
	uint8_t iid);

	OutputTerminal(fbl::RefPtr<DescriptorListMemory> desc_list,
	const usb_audio_ac_output_terminal_desc* desc,
	uint8_t iid)
	: Terminal(std::move(desc_list),
	reinterpret_cast<const usb_audio_ac_terminal_desc*>(desc), iid) {}

	DISALLOW_COPY_ASSIGN_AND_MOVE(OutputTerminal);

	const usb_audio_ac_output_terminal_desc* output_desc() const {
	return reinterpret_cast<const usb_audio_ac_output_terminal_desc*>(desc_);
	}
	};

	class MixerUnit : public AudioUnit {
	public:
	uint32_t source_count() const final { return mixer_desc()->bNrInPins; }
	uint32_t source_id(uint32_t ndx) const final {
	return (ndx < source_count()) ? mixer_desc()->baSourceID[ndx] : kInvalidID;
	}

	const usb_audio_ac_mixer_unit_desc_0* mixer_desc() const {
	return reinterpret_cast<const usb_audio_ac_mixer_unit_desc_0*>(desc_);
	}
	const usb_audio_ac_mixer_unit_desc_1* mixer_desc_1() const { return mixer_desc_1_; }
	const usb_audio_ac_mixer_unit_desc_2* mixer_desc_2() const { return mixer_desc_2_; }

	// TODO(johngro): Add a probe method to mixer so that we can read all of the
	// mix/max/cur settings for the mixer crossbar. Because of the way that we
	// are organizing our graph, this method may need to be extended to have
	// access to the set of all units present in the control interface.

	private:
	friend class AudioUnit;

	static fbl::RefPtr<MixerUnit> Create(const DescriptorListMemory::Iterator& iter, uint8_t iid);

	MixerUnit(fbl::RefPtr<DescriptorListMemory> desc_list,
	const usb_audio_ac_mixer_unit_desc_0* desc_0,
	const usb_audio_ac_mixer_unit_desc_1* desc_1,
	const usb_audio_ac_mixer_unit_desc_2* desc_2,
	uint8_t iid)
	: AudioUnit(std::move(desc_list),
	reinterpret_cast<const usb_audio_ac_ut_desc*>(desc_0),
	iid),
	mixer_desc_1_(desc_1),
	mixer_desc_2_(desc_2) {}

	DISALLOW_COPY_ASSIGN_AND_MOVE(MixerUnit);

	const usb_audio_ac_mixer_unit_desc_1* const mixer_desc_1_;
	const usb_audio_ac_mixer_unit_desc_2* const mixer_desc_2_;
	};

	class SelectorUnit : public AudioUnit {
	public:
	uint32_t source_count() const final { return selector_desc()->bNrInPins; }
	uint32_t source_id(uint32_t ndx) const final {
	return (ndx < source_count()) ? selector_desc()->baSourceID[ndx] : kInvalidID;
	}

	const usb_audio_ac_selector_unit_desc_0* selector_desc() const {
	return reinterpret_cast<const usb_audio_ac_selector_unit_desc_0*>(desc_);
	}

	const usb_audio_ac_selector_unit_desc_1* selector_desc_1() const { return selector_desc_1_; }

	// Select the input to the selector unit identified by the desired upstream
	// unit's id;
	zx_status_t Select(const usb_protocol_t& proto, uint8_t upstream_id);

	private:
	friend class AudioUnit;

	static fbl::RefPtr<SelectorUnit> Create(const DescriptorListMemory::Iterator& iter,
	uint8_t iid);

	SelectorUnit(fbl::RefPtr<DescriptorListMemory> desc_list,
	const usb_audio_ac_selector_unit_desc_0* desc_0,
	const usb_audio_ac_selector_unit_desc_1* desc_1,
	uint8_t iid)
	: AudioUnit(std::move(desc_list),
	reinterpret_cast<const usb_audio_ac_ut_desc*>(desc_0),
	iid),
	selector_desc_1_(desc_1) {}

	DISALLOW_COPY_ASSIGN_AND_MOVE(SelectorUnit);

	const usb_audio_ac_selector_unit_desc_1* const selector_desc_1_;
	};

	class FeatureUnit : public AudioUnit {
	public:
	uint32_t source_count() const final { return 1; }
	uint32_t source_id(uint32_t ndx) const final { return feature_desc()->bSourceID; }

	bool has_vol() const { return (master_feat_ \| ch_feat_) & USB_AUDIO_FU_BMA_VOLUME; }
	bool has_agc() const { return (master_feat_ \| ch_feat_) & USB_AUDIO_FU_BMA_AUTOMATIC_GAIN; }
	bool has_mute() const { return (master_feat_ \| ch_feat_) & USB_AUDIO_FU_BMA_MUTE; }

	float vol_min_db() const { return static_cast<float>(vol_min_) * kDbPerTick; }
	float vol_max_db() const { return static_cast<float>(vol_max_) * kDbPerTick; }
	float vol_res_db() const { return static_cast<float>(vol_res_) * kDbPerTick; }
	float vol_cur_db() const { return static_cast<float>(vol_cur_) * kDbPerTick; }
	bool mute_cur() const { return !!mute_cur_; }
	bool agc_cur() const { return !!agc_cur_; }

	const usb_audio_ac_feature_unit_desc_0* feature_desc() const {
	return reinterpret_cast<const usb_audio_ac_feature_unit_desc_0*>(desc_);
	}
	const usb_audio_ac_feature_unit_desc_1* feature_desc_1() const { return feature_desc_1_; }

	zx_status_t Probe(const usb_protocol_t& proto) final;

	// Do the best we can to set the volume/mute/agc. Return the value actually set.
	float SetVol (const usb_protocol_t& proto, float db);
	bool SetMute(const usb_protocol_t& proto, bool mute);
	bool SetAgc (const usb_protocol_t& proto, bool enabled);

	private:
	friend class AudioUnit;

	// Section 5.2.2.4.3.2 of the USB Audio 1.0 spec
	static constexpr float kDbPerTick = 1.0f / 256.0f;

	// A small struct used to track the various features supported by a channel
	// controlled by this feature unit.
	struct Features {
	bool has_vol() const { return supported_ & USB_AUDIO_FU_BMA_VOLUME; }
	bool has_mute() const { return supported_ & USB_AUDIO_FU_BMA_MUTE; }
	bool has_agc() const { return supported_ & USB_AUDIO_FU_BMA_AUTOMATIC_GAIN; }

	uint32_t supported_ = 0;
	int16_t vol_min_ = 0;
	int16_t vol_max_ = 0;
	int16_t vol_res_ = 0;
	int16_t vol_cur_ = 0;
	bool mute_cur = false;
	};

	static fbl::RefPtr<FeatureUnit> Create(const DescriptorListMemory::Iterator& iter, uint8_t iid);

	// Map a feature ordinal to its corresponding bit in the bmaControls
	// bitmask. Thankfully, as of the USB Audio 1.0 spec, this is just a simple
	// offset and shift operation.
	static constexpr uint32_t FeatureToBit(uint8_t ord) { return 1u << (ord - 1); }

	FeatureUnit(fbl::RefPtr<DescriptorListMemory> desc_list,
	const usb_audio_ac_feature_unit_desc_0* desc_0,
	const usb_audio_ac_feature_unit_desc_1* desc_1,
	fbl::unique_ptr<Features[]> feature_mem,
	size_t feature_len,
	uint8_t iid)
	: AudioUnit(std::move(desc_list),
	reinterpret_cast<const usb_audio_ac_ut_desc*>(desc_0),
	iid),
	feature_desc_1_(desc_1),
	features_(feature_mem.release(), feature_len) {}

	DISALLOW_COPY_ASSIGN_AND_MOVE(FeatureUnit);

	template <typename T>
	zx_status_t FeatCtrlReq(const usb_protocol_t& proto,
	uint8_t code, uint8_t ctrl, uint8_t ch, T* data) {
	// See Section 5.2.2.4 in the USB Audio 1.0 spec for the encoding of val.
	uint16_t val = static_cast<uint16_t>((static_cast<uint16_t>(ctrl) << 8) \| ch);
	return CtrlReq<T>(proto, code, val, data);
	}

	template <typename T>
	void SetFeature(const usb_protocol_t& proto, uint8_t feature, T val) {
	auto mask = FeatureToBit(feature);

	if (master_feat_ & mask) {
	FeatCtrlReq(proto, USB_AUDIO_SET_CUR, feature, 0, &val);
	} else {
	for (size_t i = 1; i < features_.size(); ++i) {
	uint8_t ch = static_cast<uint8_t>(i);
	FeatCtrlReq(proto, USB_AUDIO_SET_CUR, feature, ch, &val);
	}
	}
	}

	const usb_audio_ac_feature_unit_desc_1* const feature_desc_1_;
	const fbl::Array<Features> features_;

	uint32_t master_feat_ = 0;
	uint32_t ch_feat_ = 0;
	int16_t vol_min_ = 0;
	int16_t vol_max_ = 0;
	int16_t vol_res_ = 0;
	int16_t vol_cur_ = 0;
	uint8_t mute_cur_ = 0;
	uint8_t agc_cur_ = 0;
	};

	class ProcessingUnit : public AudioUnit {
	public:
	uint32_t source_count() const final { return processing_desc()->bNrInPins; }
	uint32_t source_id(uint32_t ndx) const final {
	return (ndx < source_count()) ? processing_desc()->baSourceID[ndx] : kInvalidID;
	}

	const usb_audio_ac_processing_unit_desc_0* processing_desc() const {
	return reinterpret_cast<const usb_audio_ac_processing_unit_desc_0*>(desc_);
	}

	const usb_audio_ac_processing_unit_desc_1* processing_desc_1() const {
	return processing_desc_1_;
	}

	const usb_audio_ac_processing_unit_desc_2* processing_desc_2() const {
	return processing_desc_2_;
	}

	private:
	friend class AudioUnit;

	static fbl::RefPtr<ProcessingUnit> Create(const DescriptorListMemory::Iterator& iter,
	uint8_t iid);

	ProcessingUnit(fbl::RefPtr<DescriptorListMemory> desc_list,
	const usb_audio_ac_processing_unit_desc_0* desc_0,
	const usb_audio_ac_processing_unit_desc_1* desc_1,
	const usb_audio_ac_processing_unit_desc_2* desc_2,
	uint8_t iid)
	: AudioUnit(std::move(desc_list),
	reinterpret_cast<const usb_audio_ac_ut_desc*>(desc_0),
	iid),
	processing_desc_1_(desc_1),
	processing_desc_2_(desc_2) {}

	DISALLOW_COPY_ASSIGN_AND_MOVE(ProcessingUnit);

	const usb_audio_ac_processing_unit_desc_1* const processing_desc_1_;
	const usb_audio_ac_processing_unit_desc_2* const processing_desc_2_;
	};

	class ExtensionUnit : public AudioUnit {
	public:
	uint32_t source_count() const final { return extension_desc()->bNrInPins; }
	uint32_t source_id(uint32_t ndx) const final {
	return (ndx < source_count()) ? extension_desc()->baSourceID[ndx] : kInvalidID;
	}

	const usb_audio_ac_extension_unit_desc_0* extension_desc() const {
	return reinterpret_cast<const usb_audio_ac_extension_unit_desc_0*>(desc_);
	}

	const usb_audio_ac_extension_unit_desc_1* extension_desc_1() const { return extension_desc_1_; }
	const usb_audio_ac_extension_unit_desc_2* extension_desc_2() const { return extension_desc_2_; }

	private:
	friend class AudioUnit;

	static fbl::RefPtr<ExtensionUnit> Create(const DescriptorListMemory::Iterator& iter,
	uint8_t iid);

	ExtensionUnit(fbl::RefPtr<DescriptorListMemory> desc_list,
	const usb_audio_ac_extension_unit_desc_0* desc_0,
	const usb_audio_ac_extension_unit_desc_1* desc_1,
	const usb_audio_ac_extension_unit_desc_2* desc_2,
	uint8_t iid)
	: AudioUnit(std::move(desc_list),
	reinterpret_cast<const usb_audio_ac_ut_desc*>(desc_0),
	iid),
	extension_desc_1_(desc_1),
	extension_desc_2_(desc_2) {}

	DISALLOW_COPY_ASSIGN_AND_MOVE(ExtensionUnit);

	const usb_audio_ac_extension_unit_desc_1* const extension_desc_1_;
	const usb_audio_ac_extension_unit_desc_2* const extension_desc_2_;
	};

	} // namespace usb
	} // namespace audio