firecracker_rs_sdk/models/
drive.rs

1use std::path::PathBuf;
2
3use serde::{Deserialize, Serialize};
4
5use super::rate_limiter::RateLimiter;
6
7#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
8pub struct Drive {
9    /// drive id
10    /// Required: true
11    #[serde(rename = "drive_id")]
12    pub drive_id: String,
13
14    /// partuuid
15    /// Represents the unique id of the boot partition of this device.
16    /// It is optional and it will be taken into account
17    /// only if the is_root_device field is true.
18    #[serde(rename = "partuuid", skip_serializing_if = "Option::is_none")]
19    pub partuuid: Option<String>,
20
21    /// is root device
22    /// Required: true
23    #[serde(rename = "is_root_device")]
24    pub is_root_device: bool,
25
26    /// cache type
27    /// Represents the caching strategy for the block device.
28    #[serde(rename = "cache_type", skip_serializing_if = "Option::is_none")]
29    pub cache_type: Option<CacheType>,
30
31    /// VirtioBlock specific parameters:
32    /// Is block read only.
33    /// This field is required for virtio-block config and should be omitted for vhost-user-block configuration.
34    /// Required: true
35    #[serde(rename = "is_read_only")]
36    pub is_read_only: bool,
37
38    /// VirtioBlock specific parameters:
39    /// Host level path for the guest drive.
40    /// This field is required for virtio-block config and should be omitted for vhost-user-block configuration.
41    /// Required: true
42    #[serde(rename = "path_on_host")]
43    pub path_on_host: PathBuf,
44
45    /// VirtioBlock specific parameters:
46    /// rate limiter
47    #[serde(rename = "rate_limiter", skip_serializing_if = "Option::is_none")]
48    pub rate_limiter: Option<RateLimiter>,
49
50    /// VirtioBlock specific parameters:
51    /// Type of the IO engine used by the device. "Async" is supported on
52    /// host kernels newer than 5.10.51.
53    /// This field is optional for virtio-block config and should be omitted for vhost-user-block configuration.
54    #[serde(rename = "io_engine", skip_serializing_if = "Option::is_none")]
55    pub io_engine: Option<IoEngine>,
56
57    /// VhostUserBlock specific parameters
58    /// Path to the socket of vhost-user-block backend.
59    /// This field is required for vhost-user-block config should be omitted for virtio-block configuration.
60    #[serde(rename = "socket", skip_serializing_if = "Option::is_none")]
61    pub socket: Option<PathBuf>,
62}
63
64/// Block device caching strategies, default to "Unsafe".
65/// Firecracker offers the possiblity of choosing the block device caching strategy.
66/// Caching strategy affects the path data written from inside the microVM takes to the host persistent storage.
67///
68/// The caching strategy should be used in order to make a trade-off:
69/// + Unsafe
70/// + + enhances performance as fewer syscalls and IO operations are performed when running workloads
71/// + + sacrifices data integrity in situations where the host simply loses the contents of the page cache without committing them to the backing storage (such as a power outage)
72/// + + recommended for use cases with ephemeral storage, such as serverless environments
73/// + Writeback
74/// + + ensures that once a flush request was acknowledged by the host, the data is committed to the backing storage
75/// + + sacrifices performance, from boot time increases to greater emulation-related latencies when running workloads
76/// + + recommended for use cases with low power environments, such as embedded environments
77#[derive(
78    Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash, Default,
79)]
80pub enum CacheType {
81    #[default]
82    #[serde(rename = "Unsafe")]
83    Unsafe,
84    #[serde(rename = "WriteBack")]
85    WriteBack,
86}
87
88/// Block device IO engine, default to "Sync".
89/// The Async engine leverages io_uring for executing requests in an async manner,
90/// therefore getting overall higher throughput by taking better advantage of the block device hardware, which typically supports queue depths greater than 1.
91/// The block IO engine is configured via the PUT /drives API call (pre-boot only), with the io_engine field taking two possible values:
92/// + Sync (default)
93/// + Async (in developer preview)
94/// The Sync variant is the default, in order to provide backwards compatibility with older Firecracker versions.
95/// Note vhost-user block device is another option for block IO that requires an external backend process.
96#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
97pub enum IoEngine {
98    #[serde(rename = "Sync")]
99    Sync,
100    /// Firecracker requires a minimum host kernel version of 5.10.51 for the Async IO engine.
101    /// This requirement is based on the availability of the io_uring subsystem, as well as a
102    /// couple of features and bugfixes that were added in newer kernel versions.
103    /// If a block device is configured with the Async io_engine on a host kernel older than
104    /// 5.10.51, the API call will return a 400 Bad Request, with a suggestive error message.
105    #[serde(rename = "Async")]
106    Async,
107}
firecracker_rs_sdk/models/drive.rs

firecracker_rs_sdk/models/
drive.rs
