nusb

The EndpointWrite struct wraps a Bulk or Interrupt OUT Endpoint to provide a high-level buffered API. It manages data transfers to the OS, allowing you to write data to a buffer that is only submitted to the USB controller when the buffer is full or when explicitly triggered.

Depending on your enabled cargo features, EndpointWrite implements several standard IO traits:

• Blocking IO: Implements std::io::Write.
• Tokio Async IO: Implements tokio::io::AsyncWrite (requires tokio feature).
• Smol Async IO: Implements futures_io::AsyncWrite (requires smol feature).

Important Behavior:

• Data is buffered and may not be sent until the buffer is full or submit(), submit_end(), flush(), or flush_end() are called.
• transfer_size determines the size of the buffer passed to the OS for each transfer. It is rounded up to the next multiple of the endpoint's max packet size.
• Backpressure is applied based on num_transfers. If the number of pending transfers reaches this limit, write calls will block (or async methods will return Pending) until a transfer completes.

// Example initialization
let endpoint_write = EndpointWrite::new(endpoint, 4096)
    .with_num_transfers(4)
    .with_write_timeout(Duration::from_secs(5));

The DeviceInfo struct provides metadata about a USB device that can be retrieved without opening it. This is typically returned by list_devices. It contains standard USB descriptor information (vendor ID, product ID, class, etc.) and platform-specific identifiers.

Platform-Specific Fields

• Linux: sysfs_path, busnum
• Windows: instance_id, parent_instance_id, port_number, driver
• macOS: registry_id, location_id

Common Methods

• id(): Returns an opaque DeviceId used to uniquely identify the device.
• vendor_id() / product_id(): Returns the 16-bit IDs from the device descriptor.
• interfaces(): Returns an iterator over InterfaceInfo objects representing the device's active interfaces.
• open(): Returns a MaybeFuture that, when awaited, attempts to open the device as a Device.

// Example of opening a device from its info
let device = device_info.open().await?;

The Buffer struct is used for bulk and interrupt transfers. It can be backed by the system allocator (default) or a platform-specific allocator for zero-copy transfers (e.g., Mmap on Linux/Android).

Usage Patterns

• OUT Transfers (Device Write): Fill the buffer with data before submitting. The len() method represents the number of initialized bytes that will be sent. Use extend_from_slice or extend_fill to populate it.
• IN Transfers (Device Read): Set the amount of data you want to receive using set_requested_len(len). The len and current contents are ignored during submission. After the transfer completes, len() will be updated to the actual number of bytes received from the device.

Key Methods

• new(requested_len: usize): Allocates a new buffer using the default allocator. The requested_len is used as the initial requested_len and the capacity will be at least that large.
• set_requested_len(&mut self, len: usize): Sets the number of bytes to request for an IN transfer. Panics if len exceeds capacity.
• clear(&mut self): Resets len to 0 for buffer reuse without changing capacity or requested_len.

use nusb::transfer::Buffer;

// For an OUT transfer
let mut buf = Buffer::new(64);
buf.extend_from_slice(b"hello");
// Submit buf for OUT transfer...

// For an IN transfer
let mut buf = Buffer::new(64);
buf.set_requested_len(64);
// Submit buf for IN transfer...
// After completion, buf.len() returns actual bytes received.

The EndpointRead struct wraps a Bulk or Interrupt IN Endpoint to provide a high-level buffered reading API. It manages multiple concurrent transfers to maximize throughput.

Depending on your enabled cargo features, you can use it with standard synchronous IO traits or asynchronous IO traits:

• Blocking IO: Implements std::io::Read and std::io::BufRead.
• Async IO (Tokio): If the tokio feature is enabled, it implements tokio::io::AsyncRead and tokio::io::AsyncBufRead.
• Async IO (Smol): If the smol feature is enabled, it implements futures_io::AsyncRead and futures_io::AsyncBufRead.

By default, EndpointRead ignores USB packet boundaries. To observe short or zero-length packets as delimiters, use the until_short_packet() method to get an EndpointReadUntilShortPacket adapter.

// Example initialization (assuming endpoint is already obtained)
let mut reader = EndpointRead::new(endpoint, 4096);

// For blocking IO
let mut buffer = [0u8; 1024];
let n = reader.read(&mut buffer)?; 

To maximize throughput and minimize latency (e.g., for high-speed data streams), you should ensure the host controller always has a transfer request pending. This is achieved by submitting multiple requests and re-submitting them as they complete.

Streaming Pattern:

1. Maintain a pool of pending transfers (e.g., check ep.pending() < threshold).
2. Allocate and submit new buffers to fill the pool.
3. In a loop, wait_next_complete for the next finished transfer.
4. Process the data and immediately submit the same buffer back to the endpoint to keep the queue full.

// Optimized Streaming Example
let mut ep_in = interface.endpoint::<Bulk, In>(0x82).unwrap();

// Keep 8 transfers pending to saturate the bus
while ep_in.pending() < 8 {
    let buffer = ep_in.allocate(16384);
    ep_in.submit(buffer);
}

loop {
    // Wait for any transfer to complete
    let completion = ep_in.wait_next_complete(Duration::MAX).unwrap();

    handle_transfer(&completion.buffer[..]);
    completion.status?; // Check for errors

    // Re-submit the buffer to maintain the pipeline
    ep_in.submit(completion.buffer);
}