blob: 53133429948db76d03d30bd93683078e00803959 [file]
// Copyright 2024 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.
#ifndef SRC_CONNECTIVITY_ETHERNET_DRIVERS_USB_CDC_FUNCTION_USB_CDC_FUNCTION_H_
#define SRC_CONNECTIVITY_ETHERNET_DRIVERS_USB_CDC_FUNCTION_USB_CDC_FUNCTION_H_
#include <endian.h>
#include <fidl/fuchsia.hardware.network.driver/cpp/driver/wire.h>
#include <fidl/fuchsia.hardware.network/cpp/fidl.h>
#include <fidl/fuchsia.hardware.usb.descriptor/cpp/fidl.h>
#include <fidl/fuchsia.hardware.usb.endpoint/cpp/fidl.h>
#include <fidl/fuchsia.hardware.usb.function/cpp/fidl.h>
#include <lib/driver/compat/cpp/compat.h>
#include <lib/driver/component/cpp/driver_base2.h>
#include <lib/fdf/cpp/dispatcher.h>
#include <lib/inspect/cpp/inspect.h>
#include <lib/sync/cpp/completion.h>
#include <zircon/listnode.h>
#include <array>
#include <deque>
#include <optional>
#include <usb-endpoint/usb-endpoint-client.h>
#include <usb-inspect/usb-inspect.h>
#include <usb/cdc.h>
#include <usb/request-fidl.h>
#include <usb/usb.h>
#include "src/lib/vmo_store/vmo_store.h"
namespace usb_cdc_function {
namespace fnetdev = fuchsia_hardware_network_driver;
namespace fdescriptor = fuchsia_hardware_usb_descriptor;
#define BULK_REQ_SIZE 2048
#define INTR_COUNT 8
#define BULK_MAX_PACKET 512 // FIXME(voydanoff) USB 3.0 support
#define INTR_MAX_PACKET sizeof(usb_cdc_speed_change_notification_t)
// Total Ethernet MTU is 1514 bytes. 1500 bytes for IP and 14 bytes for Ethernet
// header.
#define ETH_MTU 1514
#define ETH_MAC_SIZE 6
// UsbCdcFunction implements the USB CDC (Ethernet Control Model) peripheral function driver.
//
// Threading & Dispatcher Architecture:
// All protocol servers (fuchsia.hardware.usb.function/UsbFunctionInterface,
// fuchsia.hardware.network.driver/NetworkDeviceImpl), endpoint event callbacks,
// and asynchronous teardown/reconfiguration tasks run on the driver's default
// synchronized dispatcher (`dispatcher()`).
//
// Internal driver state (e.g. `online_`, `configured_`, buffer queues, and endpoint
// clients) is managed exclusively within this single dispatch loop, guaranteeing
// serialized execution without requiring explicit mutex locking.
class UsbCdcFunction : public fdf::DriverBase2,
public fdf::WireServer<fnetdev::NetworkDeviceImpl>,
public fdf::WireServer<fnetdev::NetworkPort>,
public fdf::WireServer<fnetdev::MacAddr>,
public fidl::Server<fuchsia_hardware_usb_function::UsbFunctionInterface> {
public:
static constexpr std::string_view kDriverName = "usb_cdc_function";
static constexpr uint8_t kPortId = 1;
static constexpr size_t kTxDepth = 64;
static constexpr size_t kRxDepth = 64;
static constexpr fdf_arena_tag_t kArenaTag = 'CDCE';
UsbCdcFunction()
: fdf::DriverBase2(kDriverName),
vmo_store_({
.map =
vmo_store::MapOptions{
.vm_option = ZX_VM_PERM_READ | ZX_VM_PERM_WRITE | ZX_VM_REQUIRE_NON_RESIZABLE,
.vmar = nullptr,
},
}) {}
// Unhide the inherited Start and Stop methods to avoid ambiguity with the
// fnetdev::NetworkDeviceImpl::Start and Stop methods.
using fdf::DriverBase2::Start;
using fdf::DriverBase2::Stop;
// fdf::DriverBase2 implementation.
zx::result<> Start(fdf::DriverContext context) override;
void Stop(fdf::StopCompleter completer) override;
const std::shared_ptr<fdf::Namespace> &incoming() const { return incoming_; }
// NetworkDeviceImpl protocol:
void Init(fnetdev::wire::NetworkDeviceImplInitRequest *request, fdf::Arena &arena,
InitCompleter::Sync &completer) override;
void Start(fdf::Arena &arena, StartCompleter::Sync &completer) override;
void Stop(fdf::Arena &arena, StopCompleter::Sync &completer) override;
void GetInfo(
fdf::Arena &arena,
fdf::WireServer<fnetdev::NetworkDeviceImpl>::GetInfoCompleter::Sync &completer) override;
void QueueTx(fnetdev::wire::NetworkDeviceImplQueueTxRequest *request, fdf::Arena &arena,
QueueTxCompleter::Sync &completer) override;
void QueueRxSpace(fnetdev::wire::NetworkDeviceImplQueueRxSpaceRequest *request, fdf::Arena &arena,
QueueRxSpaceCompleter::Sync &completer) override;
void PrepareVmo(fnetdev::wire::NetworkDeviceImplPrepareVmoRequest *request, fdf::Arena &arena,
PrepareVmoCompleter::Sync &completer) override;
void ReleaseVmo(fnetdev::wire::NetworkDeviceImplReleaseVmoRequest *request, fdf::Arena &arena,
ReleaseVmoCompleter::Sync &completer) override;
// NetworkPort protocol:
void GetInfo(fdf::Arena &arena,
fdf::WireServer<fnetdev::NetworkPort>::GetInfoCompleter::Sync &completer) override;
void GetStatus(fdf::Arena &arena, GetStatusCompleter::Sync &completer) override;
void SetActive(fnetdev::wire::NetworkPortSetActiveRequest *request, fdf::Arena &arena,
SetActiveCompleter::Sync &completer) override;
void GetMac(fdf::Arena &arena, GetMacCompleter::Sync &completer) override;
void Removed(fdf::Arena &arena, RemovedCompleter::Sync &completer) override;
void GetPowerDependencyToken(fdf::Arena &arena,
GetPowerDependencyTokenCompleter::Sync &completer) override;
// MacAddr protocol:
void GetAddress(fdf::Arena &arena, GetAddressCompleter::Sync &completer) override;
void GetFeatures(fdf::Arena &arena, GetFeaturesCompleter::Sync &completer) override;
void SetMode(fnetdev::wire::MacAddrSetModeRequest *request, fdf::Arena &arena,
SetModeCompleter::Sync &completer) override;
// UsbFunctionInterface methods.
void Control(ControlRequest &request, ControlCompleter::Sync &completer) override;
void SetConfigured(SetConfiguredRequest &request,
SetConfiguredCompleter::Sync &completer) override;
void SetInterface(SetInterfaceRequest &request, SetInterfaceCompleter::Sync &completer) override;
void handle_unknown_method(
fidl::UnknownMethodMetadata<fuchsia_hardware_usb_function::UsbFunctionInterface> metadata,
fidl::UnknownMethodCompleter::Sync &completer) override;
zx_status_t cdc_generate_mac_address();
void CdcIntrComplete(std::vector<fuchsia_hardware_usb_endpoint::Completion> completion);
void CdcSendNotifications();
void CdcRxComplete(std::vector<fuchsia_hardware_usb_endpoint::Completion> completions);
void CdcTxComplete(std::vector<fuchsia_hardware_usb_endpoint::Completion> completions);
void ProcessRxCompletions(std::vector<fuchsia_hardware_usb_endpoint::Completion> completions);
// test helpers.
bool HasPendingRxCompletions();
bool online() const { return online_; }
bool configured() const { return configured_; }
bool IntrEpRequestsFull() { return intr_ep_.RequestsFull(); }
const std::array<uint8_t, ETH_MAC_SIZE> &mac_addr() const { return mac_addr_; }
size_t GetInFlightInterruptCountForTesting() { return intr_ep_.GetInFlightCount(); }
uint8_t BulkInAddress() const { return descriptors_.bulk_in_ep.b_endpoint_address; }
uint8_t BulkOutAddress() const { return descriptors_.bulk_out_ep.b_endpoint_address; }
uint8_t InterruptAddress() const { return descriptors_.intr_ep.b_endpoint_address; }
inspect::ComponentInspector &inspector() { return *inspector_; }
usb_inspect::ThroughputTracker &GetThroughputTrackerForTesting() { return *throughput_tracker_; }
private:
friend class UsbCdcTestHelper;
struct SetConfiguredSharedState;
struct SetInterfaceSharedState;
void CancelSetInterface();
zx_status_t AddNetworkDevice();
fuchsia_hardware_network::PortStatus ReadStatus() const;
void UpdatePortStatus();
void DisableAllEndpoints(fit::callback<void(zx_status_t)> callback);
struct EndpointInfo {
uint8_t address;
usb::EndpointClient<UsbCdcFunction> *client;
std::string_view name;
};
std::array<EndpointInfo, 3> GetEndpoints() {
return {{
{
.address = descriptors_.intr_ep.b_endpoint_address,
.client = &intr_ep_,
.name = "intr",
},
{
.address = descriptors_.bulk_out_ep.b_endpoint_address,
.client = &bulk_out_ep_,
.name = "bulk_out",
},
{
.address = descriptors_.bulk_in_ep.b_endpoint_address,
.client = &bulk_in_ep_,
.name = "bulk_in",
},
}};
}
fidl::SyncClient<fuchsia_hardware_usb_function::UsbFunction> function_;
fidl::Client<fuchsia_hardware_usb_function::UsbFunction> async_function_;
std::string mac_addr_string_;
fdf::WireClient<fuchsia_hardware_network_driver::NetworkDeviceIfc> netdevice_ifc_;
compat::SyncInitializedDeviceServer child_;
std::shared_ptr<fdf::Namespace> incoming_;
fidl::ClientEnd<fuchsia_driver_framework::NodeController> child_controller_;
// In-direction (TX to host).
usb::EndpointClient<UsbCdcFunction> intr_ep_{usb::EndpointType::INTERRUPT, this,
std::mem_fn(&UsbCdcFunction::CdcIntrComplete)};
// Out-direction (RX from host).
usb::EndpointClient<UsbCdcFunction> bulk_out_ep_{usb::EndpointType::BULK, this,
std::mem_fn(&UsbCdcFunction::CdcRxComplete)};
// In-direction (TX to host).
usb::EndpointClient<UsbCdcFunction> bulk_in_ep_{usb::EndpointType::BULK, this,
std::mem_fn(&UsbCdcFunction::CdcTxComplete)};
// Queue of netdevice buffer IDs corresponding 1-to-1 with in-flight USB
// requests on bulk_in_ep_. An entry is std::nullopt if its netdevice buffer
// ID was already returned early by DiscardPendingTxBuffers().
std::deque<std::optional<uint32_t>> tx_completion_queue_;
std::vector<fuchsia_hardware_usb_endpoint::Completion> rx_completion_queue_;
void DiscardPendingTxBuffers(zx_status_t status);
void ReturnPendingRxSpace();
void DrainRxCompletionQueue();
void CheckStopComplete();
void CheckSetConfiguredDone();
void CheckSetInterfaceDone();
std::atomic_bool unbound_ = false; // set to true when device is going away.
bool intr_endpoint_dead_ = false;
bool rx_endpoint_dead_ = false;
bool tx_endpoint_dead_ = false;
bool deconfigure_called_ = false;
bool deconfigure_completed_ = false;
bool intr_cancelled_ = false;
bool bulk_in_cancelled_ = false;
bool bulk_out_cancelled_ = false;
std::shared_ptr<SetConfiguredSharedState> set_configured_state_;
std::shared_ptr<SetInterfaceSharedState> set_interface_state_;
// Device attributes
std::array<uint8_t, ETH_MAC_SIZE> mac_addr_;
// Guarded by the synchronized driver dispatcher.
bool online_ = false;
bool netdevice_started_ = false;
bool configured_ = false;
bool pending_notification_ = false;
fdescriptor::UsbSpeed speed_ = fdescriptor::UsbSpeed::kUndefined;
using VmoStore = vmo_store::VmoStore<vmo_store::SlabStorage<uint8_t>>;
VmoStore vmo_store_;
std::queue<fnetdev::wire::RxSpaceBuffer> rx_space_buffers_;
std::optional<fdf::StopCompleter> stop_completer_;
struct __attribute__((packed)) {
usb_interface_assoc_descriptor_t iad;
usb_interface_descriptor_t comm_intf;
usb_cs_header_interface_descriptor_t cdc_header;
usb_cs_union_interface_descriptor_1_t cdc_union;
usb_cs_ethernet_interface_descriptor_t cdc_eth;
usb_endpoint_descriptor_t intr_ep;
usb_interface_descriptor_t cdc_intf_0;
usb_interface_descriptor_t cdc_intf_1;
usb_endpoint_descriptor_t bulk_out_ep;
usb_endpoint_descriptor_t bulk_in_ep;
} descriptors_ = {
.iad =
{
.b_length = sizeof(usb_interface_assoc_descriptor_t),
.b_descriptor_type =
fidl::ToUnderlying(fdescriptor::DescriptorType::kInterfaceAssociation),
.b_first_interface = 0, // set later
.b_interface_count = 2,
.b_function_class = fidl::ToUnderlying(fdescriptor::UsbClass::kComm),
.b_function_sub_class = fidl::ToUnderlying(fdescriptor::CdcSubclass::kEthernet),
.b_function_protocol = 0,
.i_function = 0,
},
.comm_intf =
{
.b_length = sizeof(usb_interface_descriptor_t),
.b_descriptor_type = fidl::ToUnderlying(fdescriptor::DescriptorType::kInterface),
.b_interface_number = 0, // set later
.b_alternate_setting = 0,
.b_num_endpoints = 1,
.b_interface_class = fidl::ToUnderlying(fdescriptor::UsbClass::kComm),
.b_interface_sub_class = fidl::ToUnderlying(fdescriptor::CdcSubclass::kEthernet),
.b_interface_protocol = 0,
.i_interface = 0,
},
.cdc_header =
{
.bLength = sizeof(usb_cs_header_interface_descriptor_t),
.bDescriptorType = fidl::ToUnderlying(fdescriptor::DescriptorType::kCsInterface),
.bDescriptorSubType = fidl::ToUnderlying(fdescriptor::CdcDescriptorSubtype::kHeader),
.bcdCDC = 0x120,
},
.cdc_union =
{
.bLength = sizeof(usb_cs_union_interface_descriptor_1_t),
.bDescriptorType = fidl::ToUnderlying(fdescriptor::DescriptorType::kCsInterface),
.bDescriptorSubType = fidl::ToUnderlying(fdescriptor::CdcDescriptorSubtype::kUnion),
.bControlInterface = 0, // set later
.bSubordinateInterface = 0, // set later
},
.cdc_eth =
{
.bLength = sizeof(usb_cs_ethernet_interface_descriptor_t),
.bDescriptorType = fidl::ToUnderlying(fdescriptor::DescriptorType::kCsInterface),
.bDescriptorSubType =
fidl::ToUnderlying(fdescriptor::CdcDescriptorSubtype::kEthernet),
.iMACAddress = 0, // set later
.bmEthernetStatistics = 0,
.wMaxSegmentSize = ETH_MTU,
.wNumberMCFilters = 0,
.bNumberPowerFilters = 0,
},
.intr_ep =
{
.b_length = sizeof(usb_endpoint_descriptor_t),
.b_descriptor_type = fidl::ToUnderlying(fdescriptor::DescriptorType::kEndpoint),
.b_endpoint_address = 0, // set later
.bm_attributes = fidl::ToUnderlying(fdescriptor::EndpointType::kInterrupt),
.w_max_packet_size = htole16(INTR_MAX_PACKET),
.b_interval = 8,
},
.cdc_intf_0 =
{
.b_length = sizeof(usb_interface_descriptor_t),
.b_descriptor_type = fidl::ToUnderlying(fdescriptor::DescriptorType::kInterface),
.b_interface_number = 0, // set later
.b_alternate_setting = 0,
.b_num_endpoints = 0,
.b_interface_class = fidl::ToUnderlying(fdescriptor::UsbClass::kCdc),
.b_interface_sub_class = 0,
.b_interface_protocol = 0,
.i_interface = 0,
},
.cdc_intf_1 =
{
.b_length = sizeof(usb_interface_descriptor_t),
.b_descriptor_type = fidl::ToUnderlying(fdescriptor::DescriptorType::kInterface),
.b_interface_number = 0, // set later
.b_alternate_setting = 1,
.b_num_endpoints = 2,
.b_interface_class = fidl::ToUnderlying(fdescriptor::UsbClass::kCdc),
.b_interface_sub_class = 0,
.b_interface_protocol = 0,
.i_interface = 0,
},
.bulk_out_ep =
{
.b_length = sizeof(usb_endpoint_descriptor_t),
.b_descriptor_type = fidl::ToUnderlying(fdescriptor::DescriptorType::kEndpoint),
.b_endpoint_address = 0, // set later
.bm_attributes = fidl::ToUnderlying(fdescriptor::EndpointType::kBulk),
.w_max_packet_size = htole16(BULK_MAX_PACKET),
.b_interval = 0,
},
.bulk_in_ep =
{
.b_length = sizeof(usb_endpoint_descriptor_t),
.b_descriptor_type = fidl::ToUnderlying(fdescriptor::DescriptorType::kEndpoint),
.b_endpoint_address = 0, // set later
.bm_attributes = fidl::ToUnderlying(fdescriptor::EndpointType::kBulk),
.w_max_packet_size = htole16(BULK_MAX_PACKET),
.b_interval = 0,
},
};
static_assert(sizeof(descriptors_) == sizeof(usb_interface_assoc_descriptor_t) +
3 * sizeof(usb_interface_descriptor_t) +
sizeof(usb_cs_header_interface_descriptor_t) +
sizeof(usb_cs_union_interface_descriptor_1_t) +
sizeof(usb_cs_ethernet_interface_descriptor_t) +
3 * sizeof(usb_endpoint_descriptor_t),
"Descriptors struct must be packed without compiler padding");
std::optional<inspect::ComponentInspector> inspector_;
inspect::Node inspect_node_;
usb_inspect::FunctionDriverInspect function_inspect_;
usb_inspect::EndpointInspect bulk_in_inspect_;
usb_inspect::EndpointInspect bulk_out_inspect_;
usb_inspect::EndpointInspect intr_inspect_;
std::optional<usb_inspect::ThroughputTracker> throughput_tracker_;
};
} // namespace usb_cdc_function
#endif // SRC_CONNECTIVITY_ETHERNET_DRIVERS_USB_CDC_FUNCTION_USB_CDC_FUNCTION_H_