usb_vsock/
lib.rs

1// Copyright 2025 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4#![warn(missing_docs, unsafe_op_in_unsafe_fn)]
5//! A transport-agnostic library for implementing a vsock bridge over a usb bulk device.
6
7mod connection;
8mod packet;
9
10pub use connection::*;
11pub use packet::*;
12
13/// Magic sent in the sync packet of the USB protocol.
14///
15/// The 0 indicates protocol version 0, and we expect the reply sync packet to
16/// have the exact same contents. As we version the protocol this may increment.
17///
18/// To document the semantics, let's say this header were "vsock:3". The device
19/// could reply with a lower number, say "vsock:1". This is the device
20/// requesting a downgrade, and if we accept we send the final sync with
21/// "vsock:1". Otherwise we hang up.
22pub const VSOCK_MAGIC: &[u8; 7] = b"vsock:0";
23
24/// A placeholder CID indicating "any" CID is acceptable.
25pub const CID_ANY: u32 = u32::MAX;
26
27/// CID of the host.
28pub const CID_HOST: u32 = 2;
29
30/// The loopback CID.
31pub const CID_LOOPBACK: u32 = 1;
32
33/// An address for a vsock packet transmitted over USB. Since this library does not implement
34/// policy decisions, it includes all four components of a vsock address pair even though some
35/// may not be appropriate for some situations.
36#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Default)]
37pub struct Address {
38    /// For Connect, Reset, Accept, and Data packets this represents the device side's address.
39    /// Usually this will be a special value representing either that it is simply "the device",
40    /// or zero along with the rest of the cid and port fields to indicate that it's a control stream
41    /// packet. Must be zero for any other packet type.
42    pub device_cid: u32,
43    /// For Connect, Reset, Accept, and Data packets this represents the host side's address.
44    /// Usually this will be a special value representing either that it is simply "the host",
45    /// or zero along with the rest of the cid and port fields to indicate that it's a control stream
46    /// packet. Must be zero for any other packet type.
47    pub host_cid: u32,
48    /// For Connect, Reset, Accept, and Data packets this represents the device side's port.
49    /// This must be a valid positive value for any of those packet types, unless all of the cid and
50    /// port fields are also zero, in which case it is a control stream packet. Must be zero for any
51    /// other packet type.
52    pub device_port: u32,
53    /// For Connect, Reset, Accept, and Data packets this represents the host side's port.
54    /// This must be a valid positive value for any of those packet types, unless all of the cid and
55    /// port fields are also zero, in which case it is a control stream packet. Must be zero for any
56    /// other packet type.
57    pub host_port: u32,
58}
59
60impl Address {
61    /// Returns true if all the fields of this address are zero (which usually means it's a control
62    /// packet of some sort).
63    pub fn is_zeros(&self) -> bool {
64        *self == Self::default()
65    }
66}
67
68impl From<&Header> for Address {
69    fn from(header: &Header) -> Self {
70        Self {
71            device_cid: header.device_cid.get(),
72            host_cid: header.host_cid.get(),
73            device_port: header.device_port.get(),
74            host_port: header.host_port.get(),
75        }
76    }
77}
usb_vsock/lib.rs

usb_vsock/
lib.rs
