1 // Copyright (C) 2019 Alibaba Cloud Computing. All rights reserved. 2 // SPDX-License-Identifier: Apache-2.0 3 4 //! The protocol for vhost-user is based on the existing implementation of vhost for the Linux 5 //! Kernel. The protocol defines two sides of the communication, master and slave. Master is 6 //! the application that shares its virtqueues. Slave is the consumer of the virtqueues. 7 //! 8 //! The communication channel between the master and the slave includes two sub channels. One is 9 //! used to send requests from the master to the slave and optional replies from the slave to the 10 //! master. This sub channel is created on master startup by connecting to the slave service 11 //! endpoint. The other is used to send requests from the slave to the master and optional replies 12 //! from the master to the slave. This sub channel is created by the master issuing a 13 //! VHOST_USER_SET_SLAVE_REQ_FD request to the slave with an auxiliary file descriptor. 14 //! 15 //! Unix domain socket is used as the underlying communication channel because the master needs to 16 //! send file descriptors to the slave. 17 //! 18 //! Most messages that can be sent via the Unix domain socket implementing vhost-user have an 19 //! equivalent ioctl to the kernel implementation. 20 21 use std::io::Error as IOError; 22 23 pub mod message; 24 25 mod connection; 26 pub use self::connection::Listener; 27 28 #[cfg(feature = "vhost-user-master")] 29 mod master; 30 #[cfg(feature = "vhost-user-master")] 31 pub use self::master::{Master, VhostUserMaster}; 32 #[cfg(feature = "vhost-user")] 33 mod master_req_handler; 34 #[cfg(feature = "vhost-user")] 35 pub use self::master_req_handler::{ 36 MasterReqHandler, VhostUserMasterReqHandler, VhostUserMasterReqHandlerMut, 37 }; 38 39 #[cfg(feature = "vhost-user-slave")] 40 mod slave; 41 #[cfg(feature = "vhost-user-slave")] 42 pub use self::slave::SlaveListener; 43 #[cfg(feature = "vhost-user-slave")] 44 mod slave_req_handler; 45 #[cfg(feature = "vhost-user-slave")] 46 pub use self::slave_req_handler::{ 47 SlaveReqHandler, VhostUserSlaveReqHandler, VhostUserSlaveReqHandlerMut, 48 }; 49 #[cfg(feature = "vhost-user-slave")] 50 mod slave_fs_cache; 51 #[cfg(feature = "vhost-user-slave")] 52 pub use self::slave_fs_cache::SlaveFsCacheReq; 53 54 /// Errors for vhost-user operations 55 #[derive(Debug)] 56 pub enum Error { 57 /// Invalid parameters. 58 InvalidParam, 59 /// Unsupported operations due to that the protocol feature hasn't been negotiated. 60 InvalidOperation, 61 /// Invalid message format, flag or content. 62 InvalidMessage, 63 /// Only part of a message have been sent or received successfully 64 PartialMessage, 65 /// Message is too large 66 OversizedMsg, 67 /// Fd array in question is too big or too small 68 IncorrectFds, 69 /// Can't connect to peer. 70 SocketConnect(std::io::Error), 71 /// Generic socket errors. 72 SocketError(std::io::Error), 73 /// The socket is broken or has been closed. 74 SocketBroken(std::io::Error), 75 /// Should retry the socket operation again. 76 SocketRetry(std::io::Error), 77 /// Failure from the slave side. 78 SlaveInternalError, 79 /// Failure from the master side. 80 MasterInternalError, 81 /// Virtio/protocol features mismatch. 82 FeatureMismatch, 83 /// Error from request handler 84 ReqHandlerError(IOError), 85 } 86 87 impl std::fmt::Display for Error { fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result88 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result { 89 match self { 90 Error::InvalidParam => write!(f, "invalid parameters"), 91 Error::InvalidOperation => write!(f, "invalid operation"), 92 Error::InvalidMessage => write!(f, "invalid message"), 93 Error::PartialMessage => write!(f, "partial message"), 94 Error::OversizedMsg => write!(f, "oversized message"), 95 Error::IncorrectFds => write!(f, "wrong number of attached fds"), 96 Error::SocketError(e) => write!(f, "socket error: {}", e), 97 Error::SocketConnect(e) => write!(f, "can't connect to peer: {}", e), 98 Error::SocketBroken(e) => write!(f, "socket is broken: {}", e), 99 Error::SocketRetry(e) => write!(f, "temporary socket error: {}", e), 100 Error::SlaveInternalError => write!(f, "slave internal error"), 101 Error::MasterInternalError => write!(f, "Master internal error"), 102 Error::FeatureMismatch => write!(f, "virtio/protocol features mismatch"), 103 Error::ReqHandlerError(e) => write!(f, "handler failed to handle request: {}", e), 104 } 105 } 106 } 107 108 impl std::error::Error for Error {} 109 110 impl Error { 111 /// Determine whether to rebuild the underline communication channel. should_reconnect(&self) -> bool112 pub fn should_reconnect(&self) -> bool { 113 match *self { 114 // Should reconnect because it may be caused by temporary network errors. 115 Error::PartialMessage => true, 116 // Should reconnect because the underline socket is broken. 117 Error::SocketBroken(_) => true, 118 // Slave internal error, hope it recovers on reconnect. 119 Error::SlaveInternalError => true, 120 // Master internal error, hope it recovers on reconnect. 121 Error::MasterInternalError => true, 122 // Should just retry the IO operation instead of rebuilding the underline connection. 123 Error::SocketRetry(_) => false, 124 Error::InvalidParam | Error::InvalidOperation => false, 125 Error::InvalidMessage | Error::IncorrectFds | Error::OversizedMsg => false, 126 Error::SocketError(_) | Error::SocketConnect(_) => false, 127 Error::FeatureMismatch => false, 128 Error::ReqHandlerError(_) => false, 129 } 130 } 131 } 132 133 impl std::convert::From<sys_util::Error> for Error { 134 /// Convert raw socket errors into meaningful vhost-user errors. 135 /// 136 /// The sys_util::Error is a simple wrapper over the raw errno, which doesn't means 137 /// much to the vhost-user connection manager. So convert it into meaningful errors to simplify 138 /// the connection manager logic. 139 /// 140 /// # Return: 141 /// * - Error::SocketRetry: temporary error caused by signals or short of resources. 142 /// * - Error::SocketBroken: the underline socket is broken. 143 /// * - Error::SocketError: other socket related errors. 144 #[allow(unreachable_patterns)] // EWOULDBLOCK equals to EGAIN on linux from(err: sys_util::Error) -> Self145 fn from(err: sys_util::Error) -> Self { 146 match err.errno() { 147 // The socket is marked nonblocking and the requested operation would block. 148 libc::EAGAIN => Error::SocketRetry(IOError::from_raw_os_error(libc::EAGAIN)), 149 // The socket is marked nonblocking and the requested operation would block. 150 libc::EWOULDBLOCK => Error::SocketRetry(IOError::from_raw_os_error(libc::EWOULDBLOCK)), 151 // A signal occurred before any data was transmitted 152 libc::EINTR => Error::SocketRetry(IOError::from_raw_os_error(libc::EINTR)), 153 // The output queue for a network interface was full. This generally indicates 154 // that the interface has stopped sending, but may be caused by transient congestion. 155 libc::ENOBUFS => Error::SocketRetry(IOError::from_raw_os_error(libc::ENOBUFS)), 156 // No memory available. 157 libc::ENOMEM => Error::SocketRetry(IOError::from_raw_os_error(libc::ENOMEM)), 158 // Connection reset by peer. 159 libc::ECONNRESET => Error::SocketBroken(IOError::from_raw_os_error(libc::ECONNRESET)), 160 // The local end has been shut down on a connection oriented socket. In this case the 161 // process will also receive a SIGPIPE unless MSG_NOSIGNAL is set. 162 libc::EPIPE => Error::SocketBroken(IOError::from_raw_os_error(libc::EPIPE)), 163 // Write permission is denied on the destination socket file, or search permission is 164 // denied for one of the directories the path prefix. 165 libc::EACCES => Error::SocketConnect(IOError::from_raw_os_error(libc::EACCES)), 166 // Catch all other errors 167 e => Error::SocketError(IOError::from_raw_os_error(e)), 168 } 169 } 170 } 171 172 /// Result of vhost-user operations 173 pub type Result<T> = std::result::Result<T, Error>; 174 175 /// Result of request handler. 176 pub type HandlerResult<T> = std::result::Result<T, IOError>; 177 178 #[cfg(all(test, feature = "vhost-user-slave"))] 179 mod dummy_slave; 180 181 #[cfg(all(test, feature = "vhost-user-master", feature = "vhost-user-slave"))] 182 mod tests { 183 use std::os::unix::io::AsRawFd; 184 use std::path::Path; 185 use std::sync::{Arc, Barrier, Mutex}; 186 use std::thread; 187 188 use super::dummy_slave::{DummySlaveReqHandler, VIRTIO_FEATURES}; 189 use super::message::*; 190 use super::*; 191 use crate::backend::VhostBackend; 192 use crate::{VhostUserMemoryRegionInfo, VringConfigData}; 193 use tempfile::{tempfile, Builder, TempDir}; 194 temp_dir() -> TempDir195 fn temp_dir() -> TempDir { 196 Builder::new().prefix("/tmp/vhost_test").tempdir().unwrap() 197 } 198 create_slave<P, S>(path: P, backend: Arc<S>) -> (Master, SlaveReqHandler<S>) where P: AsRef<Path>, S: VhostUserSlaveReqHandler,199 fn create_slave<P, S>(path: P, backend: Arc<S>) -> (Master, SlaveReqHandler<S>) 200 where 201 P: AsRef<Path>, 202 S: VhostUserSlaveReqHandler, 203 { 204 let listener = Listener::new(&path, true).unwrap(); 205 let mut slave_listener = SlaveListener::new(listener, backend).unwrap(); 206 let master = Master::connect(&path, 1).unwrap(); 207 (master, slave_listener.accept().unwrap().unwrap()) 208 } 209 210 #[test] create_dummy_slave()211 fn create_dummy_slave() { 212 let slave = Arc::new(Mutex::new(DummySlaveReqHandler::new())); 213 214 slave.set_owner().unwrap(); 215 assert!(slave.set_owner().is_err()); 216 } 217 218 #[test] test_set_owner()219 fn test_set_owner() { 220 let slave_be = Arc::new(Mutex::new(DummySlaveReqHandler::new())); 221 let dir = temp_dir(); 222 let mut path = dir.path().to_owned(); 223 path.push("sock"); 224 let (master, mut slave) = create_slave(&path, slave_be.clone()); 225 226 assert_eq!(slave_be.lock().unwrap().owned, false); 227 master.set_owner().unwrap(); 228 slave.handle_request().unwrap(); 229 assert_eq!(slave_be.lock().unwrap().owned, true); 230 master.set_owner().unwrap(); 231 assert!(slave.handle_request().is_err()); 232 assert_eq!(slave_be.lock().unwrap().owned, true); 233 } 234 235 #[test] test_set_features()236 fn test_set_features() { 237 let mbar = Arc::new(Barrier::new(2)); 238 let sbar = mbar.clone(); 239 let dir = temp_dir(); 240 let mut path = dir.path().to_owned(); 241 path.push("sock"); 242 let slave_be = Arc::new(Mutex::new(DummySlaveReqHandler::new())); 243 let (mut master, mut slave) = create_slave(&path, slave_be.clone()); 244 245 thread::spawn(move || { 246 slave.handle_request().unwrap(); 247 assert_eq!(slave_be.lock().unwrap().owned, true); 248 249 slave.handle_request().unwrap(); 250 slave.handle_request().unwrap(); 251 assert_eq!( 252 slave_be.lock().unwrap().acked_features, 253 VIRTIO_FEATURES & !0x1 254 ); 255 256 slave.handle_request().unwrap(); 257 slave.handle_request().unwrap(); 258 assert_eq!( 259 slave_be.lock().unwrap().acked_protocol_features, 260 VhostUserProtocolFeatures::all().bits() 261 ); 262 263 sbar.wait(); 264 }); 265 266 master.set_owner().unwrap(); 267 268 // set virtio features 269 let features = master.get_features().unwrap(); 270 assert_eq!(features, VIRTIO_FEATURES); 271 master.set_features(VIRTIO_FEATURES & !0x1).unwrap(); 272 273 // set vhost protocol features 274 let features = master.get_protocol_features().unwrap(); 275 assert_eq!(features.bits(), VhostUserProtocolFeatures::all().bits()); 276 master.set_protocol_features(features).unwrap(); 277 278 mbar.wait(); 279 } 280 281 #[test] test_master_slave_process()282 fn test_master_slave_process() { 283 let mbar = Arc::new(Barrier::new(2)); 284 let sbar = mbar.clone(); 285 let dir = temp_dir(); 286 let mut path = dir.path().to_owned(); 287 path.push("sock"); 288 let slave_be = Arc::new(Mutex::new(DummySlaveReqHandler::new())); 289 let (mut master, mut slave) = create_slave(&path, slave_be.clone()); 290 291 thread::spawn(move || { 292 // set_own() 293 slave.handle_request().unwrap(); 294 assert_eq!(slave_be.lock().unwrap().owned, true); 295 296 // get/set_features() 297 slave.handle_request().unwrap(); 298 slave.handle_request().unwrap(); 299 assert_eq!( 300 slave_be.lock().unwrap().acked_features, 301 VIRTIO_FEATURES & !0x1 302 ); 303 304 slave.handle_request().unwrap(); 305 slave.handle_request().unwrap(); 306 assert_eq!( 307 slave_be.lock().unwrap().acked_protocol_features, 308 VhostUserProtocolFeatures::all().bits() 309 ); 310 311 // get_queue_num() 312 slave.handle_request().unwrap(); 313 314 // set_mem_table() 315 slave.handle_request().unwrap(); 316 317 // get/set_config() 318 slave.handle_request().unwrap(); 319 slave.handle_request().unwrap(); 320 321 // set_slave_request_fd 322 slave.handle_request().unwrap(); 323 324 // set_vring_enable 325 slave.handle_request().unwrap(); 326 327 // set_log_base,set_log_fd() 328 slave.handle_request().unwrap_err(); 329 slave.handle_request().unwrap_err(); 330 331 // set_vring_xxx 332 slave.handle_request().unwrap(); 333 slave.handle_request().unwrap(); 334 slave.handle_request().unwrap(); 335 slave.handle_request().unwrap(); 336 slave.handle_request().unwrap(); 337 slave.handle_request().unwrap(); 338 339 // get_max_mem_slots() 340 slave.handle_request().unwrap(); 341 342 // add_mem_region() 343 slave.handle_request().unwrap(); 344 345 // remove_mem_region() 346 slave.handle_request().unwrap(); 347 348 sbar.wait(); 349 }); 350 351 master.set_owner().unwrap(); 352 353 // set virtio features 354 let features = master.get_features().unwrap(); 355 assert_eq!(features, VIRTIO_FEATURES); 356 master.set_features(VIRTIO_FEATURES & !0x1).unwrap(); 357 358 // set vhost protocol features 359 let features = master.get_protocol_features().unwrap(); 360 assert_eq!(features.bits(), VhostUserProtocolFeatures::all().bits()); 361 master.set_protocol_features(features).unwrap(); 362 363 let num = master.get_queue_num().unwrap(); 364 assert_eq!(num, 2); 365 366 let eventfd = sys_util::EventFd::new().unwrap(); 367 let mem = [VhostUserMemoryRegionInfo { 368 guest_phys_addr: 0, 369 memory_size: 0x10_0000, 370 userspace_addr: 0, 371 mmap_offset: 0, 372 mmap_handle: eventfd.as_raw_fd(), 373 }]; 374 master.set_mem_table(&mem).unwrap(); 375 376 master 377 .set_config(0x100, VhostUserConfigFlags::WRITABLE, &[0xa5u8]) 378 .unwrap(); 379 let buf = [0x0u8; 4]; 380 let (reply_body, reply_payload) = master 381 .get_config(0x100, 4, VhostUserConfigFlags::empty(), &buf) 382 .unwrap(); 383 let offset = reply_body.offset; 384 assert_eq!(offset, 0x100); 385 assert_eq!(reply_payload[0], 0xa5); 386 387 master.set_slave_request_fd(eventfd.as_raw_fd()).unwrap(); 388 master.set_vring_enable(0, true).unwrap(); 389 390 // unimplemented yet 391 master.set_log_base(0, Some(eventfd.as_raw_fd())).unwrap(); 392 master.set_log_fd(eventfd.as_raw_fd()).unwrap(); 393 394 master.set_vring_num(0, 256).unwrap(); 395 master.set_vring_base(0, 0).unwrap(); 396 let config = VringConfigData { 397 queue_max_size: 256, 398 queue_size: 128, 399 flags: VhostUserVringAddrFlags::VHOST_VRING_F_LOG.bits(), 400 desc_table_addr: 0x1000, 401 used_ring_addr: 0x2000, 402 avail_ring_addr: 0x3000, 403 log_addr: Some(0x4000), 404 }; 405 master.set_vring_addr(0, &config).unwrap(); 406 master.set_vring_call(0, &eventfd).unwrap(); 407 master.set_vring_kick(0, &eventfd).unwrap(); 408 master.set_vring_err(0, &eventfd).unwrap(); 409 410 let max_mem_slots = master.get_max_mem_slots().unwrap(); 411 assert_eq!(max_mem_slots, 32); 412 413 let region_file = tempfile().unwrap(); 414 let region = VhostUserMemoryRegionInfo { 415 guest_phys_addr: 0x10_0000, 416 memory_size: 0x10_0000, 417 userspace_addr: 0, 418 mmap_offset: 0, 419 mmap_handle: region_file.as_raw_fd(), 420 }; 421 master.add_mem_region(®ion).unwrap(); 422 423 master.remove_mem_region(®ion).unwrap(); 424 425 mbar.wait(); 426 } 427 428 #[test] test_error_display()429 fn test_error_display() { 430 assert_eq!(format!("{}", Error::InvalidParam), "invalid parameters"); 431 assert_eq!(format!("{}", Error::InvalidOperation), "invalid operation"); 432 } 433 434 #[test] test_should_reconnect()435 fn test_should_reconnect() { 436 assert_eq!(Error::PartialMessage.should_reconnect(), true); 437 assert_eq!(Error::SlaveInternalError.should_reconnect(), true); 438 assert_eq!(Error::MasterInternalError.should_reconnect(), true); 439 assert_eq!(Error::InvalidParam.should_reconnect(), false); 440 assert_eq!(Error::InvalidOperation.should_reconnect(), false); 441 assert_eq!(Error::InvalidMessage.should_reconnect(), false); 442 assert_eq!(Error::IncorrectFds.should_reconnect(), false); 443 assert_eq!(Error::OversizedMsg.should_reconnect(), false); 444 assert_eq!(Error::FeatureMismatch.should_reconnect(), false); 445 } 446 447 #[test] test_error_from_sys_util_error()448 fn test_error_from_sys_util_error() { 449 let e: Error = sys_util::Error::new(libc::EAGAIN).into(); 450 if let Error::SocketRetry(e1) = e { 451 assert_eq!(e1.raw_os_error().unwrap(), libc::EAGAIN); 452 } else { 453 panic!("invalid error code conversion!"); 454 } 455 } 456 } 457