vm_superio/
lib.rs

1// Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
2//
3// Portions Copyright 2017 The Chromium OS Authors. All rights reserved.
4// Use of this source code is governed by a BSD-style license that can be
5// found in the THIRD-PARTY file.
6//
7// SPDX-License-Identifier: Apache-2.0 OR BSD-3-Clause
8
9//! Emulation for legacy devices.
10//!
11//! For now, it offers emulation support only for the Linux serial console,
12//! an Arm PL031 Real Time Clock (RTC), and an i8042 PS/2 controller that only
13//! handles the CPU reset.
14//!
15//! It also provides a [Trigger](trait.Trigger.html) interface for an object
16//! that can generate an event.
17
18#![deny(missing_docs)]
19#![deny(missing_copy_implementations)]
20
21pub mod i8042;
22pub mod rtc_pl031;
23pub mod serial;
24
25pub use i8042::I8042Device;
26pub use rtc_pl031::{Rtc, RtcState};
27pub use serial::{Serial, SerialState};
28
29use std::result::Result;
30
31/// Abstraction for a simple, push-button like interrupt mechanism.
32/// This helps in abstracting away how events/interrupts are generated when
33/// working with the emulated devices.
34///
35/// The user has to provide a `Trigger` object to the device's constructor when
36/// initializing that device. The generic type `T: Trigger` is used in the
37/// device's structure definition to mark the fact that the events notification
38/// mechanism is done via the Trigger interface.
39/// An example of how to implement the `Trigger` interface for
40/// [an eventfd wrapper](https://docs.rs/vmm-sys-util/latest/vmm_sys_util/eventfd/index.html)
41/// can be found in the
42/// [`Example` section from `Serial`](../vm_superio/serial/struct.Serial.html#example).
43/// The `EventFd` is wrapped in the `EventFdTrigger` newtype because Rust
44/// doesn't allow implementing an external trait on external types. To get
45/// around this restriction, the newtype pattern can be used. More details
46/// about this,
47/// [here](https://doc.rust-lang.org/book/ch19-03-advanced-traits.html#using-the-newtype-pattern-to-implement-external-traits-on-external-types).
48pub trait Trigger {
49    /// Underlying type for the potential error conditions returned by `Self::trigger`.
50    type E: std::fmt::Debug;
51
52    /// Trigger an event.
53    fn trigger(&self) -> Result<(), Self::E>;
54}
vm_superio/lib.rs

vm_superio/
lib.rs
