devices/usb/backend/host_backend/
host_device.rs

1// Copyright 2019 The ChromiumOS Authors
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use std::collections::HashMap;
6use std::mem;
7use std::sync::Arc;
8use std::sync::RwLock;
9
10use base::debug;
11use base::error;
12use base::AsRawDescriptor;
13use base::RawDescriptor;
14use sync::Mutex;
15use usb_util::ConfigDescriptorTree;
16use usb_util::DescriptorHeader;
17use usb_util::Device;
18use usb_util::DeviceDescriptorTree;
19use usb_util::DeviceSpeed;
20use usb_util::InterfaceDescriptor;
21use usb_util::Transfer;
22use usb_util::TransferBuffer;
23use usb_util::TransferHandle;
24use usb_util::TransferStatus;
25use usb_util::UsbRequestSetup;
26use zerocopy::IntoBytes;
27
28use crate::usb::backend::device::BackendDevice;
29use crate::usb::backend::device::DeviceState;
30use crate::usb::backend::endpoint::ControlEndpointState;
31use crate::usb::backend::endpoint::UsbEndpoint;
32use crate::usb::backend::error::Error;
33use crate::usb::backend::error::Result;
34use crate::usb::backend::transfer::BackendTransfer;
35use crate::usb::backend::transfer::BackendTransferHandle;
36use crate::usb::backend::transfer::BackendTransferType;
37use crate::usb::backend::transfer::ControlTransferState;
38use crate::usb::backend::transfer::GenericTransferHandle;
39use crate::usb::xhci::scatter_gather_buffer::ScatterGatherBuffer;
40use crate::usb::xhci::xhci_backend_device::BackendType;
41use crate::usb::xhci::xhci_backend_device::UsbDeviceAddress;
42use crate::usb::xhci::xhci_backend_device::XhciBackendDevice;
43use crate::utils::EventLoop;
44
45/// Host device is a device connected to host.
46pub struct HostDevice {
47    pub device: Arc<Mutex<Device>>,
48    alt_settings: HashMap<u8, u8>,
49    claimed_interfaces: Vec<u8>,
50    state: Arc<RwLock<DeviceState>>,
51    control_transfer_state: Arc<RwLock<ControlTransferState>>,
52}
53
54impl HostDevice {
55    /// Create a new host device.
56    pub fn new(device: Arc<Mutex<Device>>, state: DeviceState) -> Result<HostDevice> {
57        let control_transfer_state = ControlTransferState {
58            ctl_ep_state: ControlEndpointState::SetupStage,
59            control_request_setup: UsbRequestSetup::new(0, 0, 0, 0, 0),
60            executed: false,
61        };
62        let mut host_device = HostDevice {
63            device,
64            alt_settings: HashMap::new(),
65            claimed_interfaces: vec![],
66            state: Arc::new(RwLock::new(state)),
67            control_transfer_state: Arc::new(RwLock::new(control_transfer_state)),
68        };
69
70        let config_descriptor = host_device.get_active_config_descriptor()?;
71        host_device.claim_interfaces(&config_descriptor);
72
73        Ok(host_device)
74    }
75
76    // Execute a Get Descriptor control request with type Configuration.
77    // This function is used to return a filtered version of the host device's configuration
78    // descriptor that only includes the interfaces in `self.claimed_interfaces`.
79    pub fn get_config_descriptor_filtered(
80        &mut self,
81        buffer: &ScatterGatherBuffer,
82        descriptor_index: u8,
83    ) -> Result<(TransferStatus, u32)> {
84        let _trace = cros_tracing::trace_event!(
85            USB,
86            "host_device get_config_descriptor_filtered",
87            descriptor_index
88        );
89
90        let config_descriptor = self.get_config_descriptor_by_index(descriptor_index)?;
91
92        let device_descriptor = self.get_device_descriptor_tree()?;
93        let config_start = config_descriptor.offset();
94        let config_end = config_start + config_descriptor.wTotalLength as usize;
95        let mut descriptor_data = device_descriptor.raw()[config_start..config_end].to_vec();
96
97        if config_descriptor.bConfigurationValue == self.get_active_configuration()? {
98            for i in 0..config_descriptor.bNumInterfaces {
99                if !self.claimed_interfaces.contains(&i) {
100                    // Rewrite descriptors for unclaimed interfaces to vendor-specific class.
101                    // This prevents them from being recognized by the guest drivers.
102                    let alt_setting = self.alt_settings.get(&i).unwrap_or(&0);
103                    let interface = config_descriptor
104                        .get_interface_descriptor(i, *alt_setting)
105                        .ok_or(Error::GetInterfaceDescriptor(i, *alt_setting))?;
106                    let mut interface_data: InterfaceDescriptor = **interface;
107                    interface_data.bInterfaceClass = 0xFF;
108                    interface_data.bInterfaceSubClass = 0xFF;
109                    interface_data.bInterfaceProtocol = 0xFF;
110
111                    let interface_start =
112                        interface.offset() + mem::size_of::<DescriptorHeader>() - config_start;
113                    let interface_end = interface_start + mem::size_of::<InterfaceDescriptor>();
114                    descriptor_data[interface_start..interface_end]
115                        .copy_from_slice(interface_data.as_bytes());
116                }
117            }
118        }
119
120        let bytes_transferred = buffer.write(&descriptor_data).map_err(Error::WriteBuffer)?;
121        Ok((TransferStatus::Completed, bytes_transferred as u32))
122    }
123
124    pub fn set_interface(&mut self, interface: u8, alt_setting: u8) -> Result<TransferStatus> {
125        let _trace = cros_tracing::trace_event!(USB, "host_device set_interface");
126        // It's a standard, set_interface, interface request.
127        self.device
128            .lock()
129            .set_interface_alt_setting(interface, alt_setting)
130            .map_err(Error::SetInterfaceAltSetting)?;
131        self.alt_settings.insert(interface, alt_setting);
132        let config = self.get_active_configuration()?;
133        let config_descriptor = self.get_config_descriptor(config)?;
134        self.create_endpoints(&config_descriptor)?;
135        Ok(TransferStatus::Completed)
136    }
137
138    pub fn claim_interfaces(&mut self, config_descriptor: &ConfigDescriptorTree) {
139        for i in 0..config_descriptor.num_interfaces() {
140            match self.device.lock().claim_interface(i) {
141                Ok(()) => {
142                    debug!("usb: claimed interface {}", i);
143                    self.claimed_interfaces.push(i);
144                }
145                Err(e) => {
146                    error!("unable to claim interface {}: {:?}", i, e);
147                }
148            }
149        }
150    }
151
152    pub fn release_interfaces(&mut self) {
153        let device_locked = self.device.lock();
154        for i in &self.claimed_interfaces {
155            if let Err(e) = device_locked.release_interface(*i) {
156                error!("could not release interface: {:?}", e);
157            }
158        }
159        self.claimed_interfaces = Vec::new();
160    }
161}
162
163impl AsRawDescriptor for HostDevice {
164    fn as_raw_descriptor(&self) -> RawDescriptor {
165        self.device.lock().as_raw_descriptor()
166    }
167}
168
169impl GenericTransferHandle for TransferHandle {
170    fn cancel(&self) -> Result<()> {
171        TransferHandle::cancel(self).map_err(Error::TransferHandle)
172    }
173}
174
175impl BackendDevice for HostDevice {
176    fn submit_backend_transfer(
177        &mut self,
178        transfer: BackendTransferType,
179    ) -> Result<BackendTransferHandle> {
180        match transfer {
181            BackendTransferType::HostDevice(transfer) => self
182                .device
183                .lock()
184                .submit_transfer(transfer)
185                .map_err(Error::CreateTransfer)
186                .map(BackendTransferHandle::new),
187            _ => Err(Error::MalformedBackendTransfer),
188        }
189    }
190
191    fn detach_event_handler(&self, event_loop: &Arc<EventLoop>) -> Result<()> {
192        event_loop
193            .remove_event_for_descriptor(self)
194            .map_err(Error::RemoveFromEventLoop)
195    }
196
197    fn request_transfer_buffer(&mut self, size: usize) -> TransferBuffer {
198        match self.device.lock().reserve_dma_buffer(size) {
199            Ok(dmabuf) => TransferBuffer::Dma(dmabuf),
200            Err(_) => TransferBuffer::Vector(vec![0u8; size]),
201        }
202    }
203
204    fn build_bulk_transfer(
205        &mut self,
206        ep_addr: u8,
207        transfer_buffer: TransferBuffer,
208        stream_id: Option<u16>,
209    ) -> Result<BackendTransferType> {
210        Ok(BackendTransferType::HostDevice(
211            Transfer::new_bulk(ep_addr, transfer_buffer, stream_id)
212                .map_err(Error::CreateTransfer)?,
213        ))
214    }
215
216    fn build_interrupt_transfer(
217        &mut self,
218        ep_addr: u8,
219        transfer_buffer: TransferBuffer,
220    ) -> Result<BackendTransferType> {
221        Ok(BackendTransferType::HostDevice(
222            Transfer::new_interrupt(ep_addr, transfer_buffer).map_err(Error::CreateTransfer)?,
223        ))
224    }
225
226    fn build_isochronous_transfer(
227        &mut self,
228        ep_addr: u8,
229        transfer_buffer: TransferBuffer,
230        packet_size: u32,
231    ) -> Result<BackendTransferType> {
232        Ok(BackendTransferType::HostDevice(
233            Transfer::new_isochronous(ep_addr, transfer_buffer, packet_size)
234                .map_err(Error::CreateTransfer)?,
235        ))
236    }
237
238    fn get_control_transfer_state(&mut self) -> Arc<RwLock<ControlTransferState>> {
239        self.control_transfer_state.clone()
240    }
241
242    fn get_device_state(&mut self) -> Arc<RwLock<DeviceState>> {
243        self.state.clone()
244    }
245
246    fn get_active_config_descriptor(&mut self) -> Result<ConfigDescriptorTree> {
247        let cur_config = self.get_active_configuration()?;
248        self.get_config_descriptor(cur_config)
249    }
250
251    fn get_config_descriptor(&mut self, config: u8) -> Result<ConfigDescriptorTree> {
252        self.device
253            .lock()
254            .get_config_descriptor(config)
255            .map_err(Error::GetActiveConfig)
256    }
257
258    fn get_config_descriptor_by_index(&mut self, config_index: u8) -> Result<ConfigDescriptorTree> {
259        self.device
260            .lock()
261            .get_config_descriptor_by_index(config_index)
262            .map_err(Error::GetConfigDescriptor)
263    }
264
265    fn get_device_descriptor_tree(&mut self) -> Result<DeviceDescriptorTree> {
266        Ok(self.device.lock().get_device_descriptor_tree().clone())
267    }
268
269    fn get_active_configuration(&mut self) -> Result<u8> {
270        self.device
271            .lock()
272            .get_active_configuration()
273            .map_err(Error::GetActiveConfig)
274    }
275
276    fn set_active_configuration(&mut self, config: u8) -> Result<()> {
277        self.device
278            .lock()
279            .set_active_configuration(config)
280            .map_err(Error::SetActiveConfig)
281    }
282
283    fn clear_feature(&mut self, value: u16, index: u16) -> Result<TransferStatus> {
284        // It's a standard, clear_feature, endpoint request.
285        const STD_FEATURE_ENDPOINT_HALT: u16 = 0;
286        if value == STD_FEATURE_ENDPOINT_HALT {
287            self.device
288                .lock()
289                .clear_halt(index as u8)
290                .map_err(Error::ClearHalt)?;
291        }
292        Ok(TransferStatus::Completed)
293    }
294
295    fn create_endpoints(&mut self, config_descriptor: &ConfigDescriptorTree) -> Result<()> {
296        let mut endpoints = Vec::new();
297        let device_state = self.get_device_state();
298        for i in &self.claimed_interfaces {
299            let alt_setting = self.alt_settings.get(i).unwrap_or(&0);
300            let interface = config_descriptor
301                .get_interface_descriptor(*i, *alt_setting)
302                .ok_or(Error::GetInterfaceDescriptor(*i, *alt_setting))?;
303            for ep_idx in 0..interface.bNumEndpoints {
304                let ep_dp = interface
305                    .get_endpoint_descriptor(ep_idx)
306                    .ok_or(Error::GetEndpointDescriptor(ep_idx))?;
307                let ep_num = ep_dp.get_endpoint_number();
308                if ep_num == 0 {
309                    continue;
310                }
311                let direction = ep_dp.get_direction();
312                let ty = ep_dp.get_endpoint_type().ok_or(Error::GetEndpointType)?;
313                endpoints.push(UsbEndpoint::new(
314                    device_state.read().unwrap().fail_handle.clone(),
315                    device_state.read().unwrap().job_queue.clone(),
316                    ep_num,
317                    direction,
318                    ty,
319                ));
320            }
321        }
322        device_state.write().unwrap().endpoints = endpoints;
323        Ok(())
324    }
325
326    fn reset_control_transfer_state(&mut self) {
327        let control_transfer_state = ControlTransferState {
328            ctl_ep_state: ControlEndpointState::SetupStage,
329            control_request_setup: UsbRequestSetup::new(0, 0, 0, 0, 0),
330            executed: false,
331        };
332        self.control_transfer_state = Arc::new(RwLock::new(control_transfer_state));
333    }
334
335    fn is_lost(&self) -> bool {
336        self.device.lock().is_device_lost()
337    }
338
339    fn can_finalize(&self) -> bool {
340        self.device.lock().ready_to_detach()
341    }
342}
343
344impl XhciBackendDevice for HostDevice {
345    fn get_backend_type(&self) -> BackendType {
346        let d = match self.device.lock().get_device_descriptor() {
347            Ok(d) => d,
348            Err(_) => return BackendType::Usb2,
349        };
350
351        // See definition of bcdUsb.
352        const USB3_MASK: u16 = 0x0300;
353        match d.bcdUSB & USB3_MASK {
354            USB3_MASK => BackendType::Usb3,
355            _ => BackendType::Usb2,
356        }
357    }
358
359    fn get_vid(&self) -> u16 {
360        match self.device.lock().get_device_descriptor() {
361            Ok(d) => d.idVendor,
362            Err(e) => {
363                error!("cannot get device descriptor: {:?}", e);
364                0
365            }
366        }
367    }
368
369    fn get_pid(&self) -> u16 {
370        match self.device.lock().get_device_descriptor() {
371            Ok(d) => d.idProduct,
372            Err(e) => {
373                error!("cannot get device descriptor: {:?}", e);
374                0
375            }
376        }
377    }
378
379    fn set_address(&mut self, _address: UsbDeviceAddress) {
380        // It's a standard, set_address, device request. We do nothing here. As described in XHCI
381        // spec. See set address command ring trb.
382        debug!(
383            "usb set address control transfer is received with address: {}",
384            _address
385        );
386    }
387
388    fn reset(&mut self) -> Result<()> {
389        self.device.lock().reset().map_err(Error::Reset)
390    }
391
392    fn get_speed(&self) -> Option<DeviceSpeed> {
393        self.device.lock().get_speed().unwrap_or(None)
394    }
395
396    fn alloc_streams(&self, ep: u8, num_streams: u16) -> Result<()> {
397        self.device
398            .lock()
399            .alloc_streams(ep, num_streams)
400            .map_err(Error::AllocStreams)
401    }
402
403    fn free_streams(&self, ep: u8) -> Result<()> {
404        self.device
405            .lock()
406            .free_streams(ep)
407            .map_err(Error::FreeStreams)
408    }
409
410    fn stop(&mut self) {
411        let device = self.device.lock();
412        device.set_detaching();
413
414        // Actively release interfaces to force the host kernel to cancel all in-flight URBs
415        // immediately. This prevents lingering sessions from blocking subsequent attach requests
416        // for the same physical device.
417        for &ifnum in &self.claimed_interfaces {
418            // We ignore errors here because the device or interface might have been physically
419            // removed already.
420            let _ = device.release_interface(ifnum);
421        }
422        self.claimed_interfaces.clear();
423    }
424}
425
426impl BackendTransfer for Transfer {
427    fn status(&self) -> TransferStatus {
428        Transfer::status(self)
429    }
430
431    fn actual_length(&self) -> usize {
432        Transfer::actual_length(self)
433    }
434
435    fn buffer(&self) -> &TransferBuffer {
436        &self.buffer
437    }
438
439    fn set_callback<C: 'static + Fn(BackendTransferType) + Send + Sync>(&mut self, cb: C) {
440        Transfer::set_callback(self, move |t| cb(BackendTransferType::HostDevice(t)));
441    }
442}
devices/usb/backend/host_backend/host_device.rs

devices/usb/backend/host_backend/
host_device.rs
