LibXR::USB::DeviceComposition Class Reference

USB 组合管理器：class 列表、字符串、BOS、配置切换 USB composition manager: class list, strings, BOS, and configuration switching. More...

#include <device_composition.hpp>

Public Member Functions
	DeviceComposition (EndpointPool &endpoint_pool, const std::initializer_list< const DescriptorStrings::LanguagePack * > &lang_list, const std::initializer_list< const std::initializer_list< ConfigDescriptorItem * > > &configs, ConstRawData uid={nullptr, 0}, uint8_t bmAttributes=CFG_BUS_POWERED, uint8_t bMaxPower=50)
	构造 USB 组合管理器 Construct the USB composition manager.
	DeviceComposition (const DeviceComposition &)=delete
DeviceComposition &	operator= (const DeviceComposition &)=delete
	DeviceComposition (DeviceComposition &&)=delete
DeviceComposition &	operator= (DeviceComposition &&)=delete
void	Init (bool in_isr)
	初始化当前 configuration 的运行态资源 Initialize runtime resources for the active configuration.
void	Deinit (bool in_isr)
	释放当前 configuration 的运行态资源 Release runtime resources for the active configuration.
ErrorCode	SwitchConfig (size_t index, bool in_isr)
	切换到指定 configuration value Switch to the given configuration value.
ErrorCode	BuildConfigDescriptor ()
	生成当前 configuration 描述符缓存 Build the current configuration descriptor cache.
RawData	GetConfigDescriptor () const
	获取当前 configuration 描述符缓存 Get the current configuration descriptor cache.
ConstRawData	GetBosDescriptor ()
	获取当前 BOS 描述符缓存 / Get the current BOS descriptor cache
ErrorCode	ProcessBosVendorRequest (bool in_isr, const SetupPacket *setup, BosVendorResult &result)
	分发 BOS vendor request / Dispatch BOS vendor requests
ErrorCode	GetStringDescriptor (uint8_t string_index, uint16_t lang, ConstRawData &data)
	获取字符串描述符（含 interface string） Get a string descriptor, including runtime-generated interface strings.
bool	IsComposite () const
	是否为复合设备 / Whether this is a composite device
ErrorCode	TryOverrideDeviceDescriptor (DeviceDescriptor &descriptor)
	用当前配置覆盖 device descriptor 的类字段 Try to override device-descriptor class fields from the current configuration.
size_t	GetConfigNum () const
	配置数量 / Number of configurations
size_t	GetCurrentConfig () const
	当前 configuration value / Current configuration value
uint16_t	GetDeviceStatus () const
	设备 GET_STATUS 返回值 / Device-level GET_STATUS value
DeviceClass *	FindClassByInterfaceNumber (size_t index) const
	按接口号查找所属 class Find the owning class by interface number.
DeviceClass *	FindClassByEndpointAddress (uint8_t addr) const
	按端点地址查找所属 class Find the owning class by endpoint address.

Detailed Description

USB 组合管理器：class 列表、字符串、BOS、配置切换 USB composition manager: class list, strings, BOS, and configuration switching.

Definition at line 20 of file device_composition.hpp.

Constructor & Destructor Documentation

DeviceComposition()

DeviceComposition::DeviceComposition	(	EndpointPool &	endpoint_pool,
		const std::initializer_list< const DescriptorStrings::LanguagePack * > &	lang_list,
		const std::initializer_list< const std::initializer_list< ConfigDescriptorItem * > > &	configs,
		ConstRawData	uid = {nullptr, 0},
		uint8_t	bmAttributes = CFG_BUS_POWERED,
		uint8_t	bMaxPower = 50 )

构造 USB 组合管理器 Construct the USB composition manager.

负责把 class/config/string/BOS 相关静态信息整理成 DeviceCore 可直接使用的形态。 This flattens class/config/string/BOS metadata into the shape consumed by DeviceCore.

Definition at line 345 of file device_composition.cpp.

    : endpoint_pool_(endpoint_pool),
      bm_attributes_(bmAttributes),
      composite_(is_composite_device(configs)),
      config_num_(configs.size()),
      items_(new ConfigItems[config_num_]),
      classes_(new DeviceClass*[calc_total_item_num(configs)]),
      strings_(lang_list, reinterpret_cast<const uint8_t*>(uid.addr_), uid.size_),
      bos_(calc_bos_descriptor_size_max(configs), calc_bos_capability_num_max(configs)),
      config_desc_(ConfigDescriptor::CalcMaxConfigSize(configs), bmAttributes, bMaxPower)
{
  ASSERT(config_num_ > 0);
 
  // 将所有配置项整理成：
  // 1) 每个 configuration 自己的 item 表
  // 2) 一份用于字符串注册的唯一 class 表
  // Flatten every configuration item into:
  // 1) per-config item tables for descriptor building / binding
  // 2) one unique class table for string registration
  size_t config_index = 0;
  for (const auto& cfg_group : configs)
  {
    items_[config_index].item_num = cfg_group.size();
    items_[config_index].items = new ConfigDescriptorItem*[cfg_group.size()];
 
    size_t item_index = 0;
    for (auto* item : cfg_group)
    {
      items_[config_index].items[item_index++] = item;
      auto* device_class = static_cast<DeviceClass*>(item);
      if (device_class != nullptr &&
          !contains_class(classes_, class_count_, device_class))
      {
        classes_[class_count_++] = device_class;
      }
    }
 
    ++config_index;
  }
 
  // 初始化阶段一次性算出接口字符串容量和最大描述符空间。
  // Pre-compute interface-string storage once during initialization.
  const auto interface_string_layout =
      calc_interface_string_layout(classes_, class_count_);
  interface_string_count_ = interface_string_layout.count;
  if (interface_string_count_ > 0)
  {
    interface_strings_ = new const char*[interface_string_count_];
    interface_string_buffer_.addr_ = new uint8_t[interface_string_layout.max_len + 2];
    interface_string_buffer_.size_ = interface_string_layout.max_len + 2;
  }
 
  RegisterInterfaceStrings();
}

Member Function Documentation

BuildConfigDescriptor()

LibXR::ErrorCode DeviceComposition::BuildConfigDescriptor

(

)

生成当前 configuration 描述符缓存 Build the current configuration descriptor cache.

Definition at line 454 of file device_composition.cpp.

{
  // ConfigDescriptor 只构建当前激活的 configuration；
  // current_cfg_ 同时决定 item 表和对外可见的 bConfigurationValue。
  // ConfigDescriptor builds the active configuration only;
  // current_cfg_ supplies both the item table and the externally visible
  // bConfigurationValue.
  const auto& config = CurrentConfigItems();
  return config_desc_.BuildConfigDescriptor(config.items, config.item_num,
                                            static_cast<uint8_t>(current_cfg_ + 1),
                                            i_configuration_);
}

Deinit()

void DeviceComposition::Deinit

(

bool

in_isr

)

释放当前 configuration 的运行态资源 Release runtime resources for the active configuration.

Definition at line 421 of file device_composition.cpp.

{
  UnbindEndpoints(in_isr);
  configured_ = false;
  current_cfg_ = 0;
}

FindClassByEndpointAddress()

DeviceClass * DeviceComposition::FindClassByEndpointAddress ( uint8_t addr ) const

nodiscard

按端点地址查找所属 class Find the owning class by endpoint address.

Definition at line 573 of file device_composition.cpp.

{
  if (!configured_)
  {
    return nullptr;
  }
 
  const auto& config = CurrentConfigItems();
 
  for (size_t i = 0; i < config.item_num; ++i)
  {
    auto* item = config.items[i];
    if (item == nullptr)
    {
      continue;
    }
 
    if (item->OwnsEndpoint(addr))
    {
      return static_cast<DeviceClass*>(item);
    }
  }
 
  return nullptr;
}

FindClassByInterfaceNumber()

DeviceClass * DeviceComposition::FindClassByInterfaceNumber ( size_t index ) const

nodiscard

按接口号查找所属 class Find the owning class by interface number.

Definition at line 541 of file device_composition.cpp.

{
  if (!configured_)
  {
    return nullptr;
  }
 
  const auto& config = CurrentConfigItems();
 
  // 每个 item 都声明自己占用的接口数量；
  // 沿扁平表前进，直到目标接口落入某个 item 的区间。
  // Each item reports how many interfaces it occupies; walk the flattened list
  // until the requested interface falls into one item's local range.
  int interface_index = -1;
  for (size_t i = 0; i < config.item_num; ++i)
  {
    auto* item = config.items[i];
    if (item == nullptr)
    {
      continue;
    }
 
    interface_index += static_cast<int>(item->GetInterfaceCount());
    if (interface_index >= static_cast<int>(index))
    {
      return static_cast<DeviceClass*>(item);
    }
  }
 
  return nullptr;
}

GetBosDescriptor()

ConstRawData DeviceComposition::GetBosDescriptor ( )

nodiscard

获取当前 BOS 描述符缓存 / Get the current BOS descriptor cache

Definition at line 469 of file device_composition.cpp.

{ return bos_.GetBosDescriptor(); }

GetConfigDescriptor()

RawData DeviceComposition::GetConfigDescriptor ( ) const

nodiscard

获取当前 configuration 描述符缓存 Get the current configuration descriptor cache.

Definition at line 467 of file device_composition.cpp.

{ return config_desc_.GetData(); }

GetConfigNum()

size_t DeviceComposition::GetConfigNum ( ) const

nodiscard

配置数量 / Number of configurations

Definition at line 528 of file device_composition.cpp.

{ return config_num_; }

GetCurrentConfig()

size_t DeviceComposition::GetCurrentConfig ( ) const

nodiscard

当前 configuration value / Current configuration value

Definition at line 530 of file device_composition.cpp.

{
  return configured_ ? static_cast<size_t>(current_cfg_ + 1u) : 0u;
}

GetDeviceStatus()

uint16_t DeviceComposition::GetDeviceStatus ( ) const

nodiscard

设备 GET_STATUS 返回值 / Device-level GET_STATUS value

Definition at line 535 of file device_composition.cpp.

{
  return ((bm_attributes_ & CFG_SELF_POWERED) ? 0x01 : 0x00) |
         ((bm_attributes_ & CFG_REMOTE_WAKEUP) ? 0x02 : 0x00);
}

GetStringDescriptor()

LibXR::ErrorCode DeviceComposition::GetStringDescriptor	(	uint8_t	string_index,
		uint16_t	lang,
		ConstRawData &	data )

获取字符串描述符（含 interface string） Get a string descriptor, including runtime-generated interface strings.

Definition at line 478 of file device_composition.cpp.

{
  if (string_index == 0)
  {
    data = ConstRawData(strings_.GetLangIDData());
    return LibXR::ErrorCode::OK;
  }
 
  if (string_index > static_cast<uint8_t>(DescriptorStrings::Index::SERIAL_NUMBER_STRING))
  {
    // 接口字符串与内建字符串集合共用同一套语言号校验。
    // Interface strings share the same language gate as the built-in string set.
    if (!strings_.HasLanguage(lang))
    {
      return LibXR::ErrorCode::NOT_FOUND;
    }
    return GenerateInterfaceString(string_index, data);
  }
 
  auto ec =
      strings_.GenerateString(static_cast<DescriptorStrings::Index>(string_index), lang);
  if (ec != LibXR::ErrorCode::OK)
  {
    return ec;
  }
 
  data = ConstRawData(strings_.GetData());
  return LibXR::ErrorCode::OK;
}

Init()

void DeviceComposition::Init

(

bool

in_isr

)

初始化当前 configuration 的运行态资源 Initialize runtime resources for the active configuration.

Definition at line 412 of file device_composition.cpp.

{
  // Init 先绑定端点，再按当前激活配置重建 BOS 视图。
  // Init binds endpoints first, then rebuilds the BOS view for the active configuration.
  configured_ = false;
  BindEndpoints(in_isr);
  RebuildBosCache();
}

IsComposite()

bool DeviceComposition::IsComposite ( ) const

nodiscard

是否为复合设备 / Whether this is a composite device

Definition at line 509 of file device_composition.cpp.

{ return composite_; }

ProcessBosVendorRequest()

LibXR::ErrorCode DeviceComposition::ProcessBosVendorRequest	(	bool	in_isr,
		const SetupPacket *	setup,
		BosVendorResult &	result )

分发 BOS vendor request / Dispatch BOS vendor requests

Definition at line 471 of file device_composition.cpp.

{
  return bos_.ProcessVendorRequest(in_isr, setup, result);
}

SwitchConfig()

LibXR::ErrorCode DeviceComposition::SwitchConfig	(	size_t	index,
		bool	in_isr )

切换到指定 configuration value Switch to the given configuration value.

Definition at line 428 of file device_composition.cpp.

{
  if (index > config_num_)
  {
    return LibXR::ErrorCode::NOT_FOUND;
  }
 
  if (index == 0)
  {
    UnbindEndpoints(in_isr);
    configured_ = false;
    current_cfg_ = 0;
    RebuildBosCache();
    return LibXR::ErrorCode::OK;
  }
 
  // USB configuration value 从 1 开始，而 current_cfg_ 内部保存的是从 0 开始的槽位。
  // USB configuration values are 1-based, while current_cfg_ stores a 0-based slot index.
  UnbindEndpoints(in_isr);
  current_cfg_ = static_cast<uint8_t>(index - 1);
  configured_ = true;
  BindEndpoints(in_isr);
  RebuildBosCache();
  return LibXR::ErrorCode::OK;
}

TryOverrideDeviceDescriptor()

LibXR::ErrorCode DeviceComposition::TryOverrideDeviceDescriptor

(

DeviceDescriptor &

descriptor

)

用当前配置覆盖 device descriptor 的类字段 Try to override device-descriptor class fields from the current configuration.

Definition at line 511 of file device_composition.cpp.

{
  if (config_num_ != 1)
  {
    return LibXR::ErrorCode::NOT_SUPPORT;
  }
 
  const auto config = items_[0];
  if (!is_device_descriptor_override_eligible(config.items, config.item_num))
  {
    return LibXR::ErrorCode::NOT_SUPPORT;
  }
 
  return config.items[0]->WriteDeviceDescriptor(descriptor);
}

---

The documentation for this class was generated from the following files:

• src/driver/usb/device/device_composition.hpp
• src/driver/usb/device/device_composition.cpp