firecracker_rs_sdk/models/cpu_template.rs
1use serde::{Deserialize, Serialize};
2
3/// The CPU Template defines a set of flags to be disabled from the microvm so that
4/// the features exposed to the guest are the same as in the selected instance type.
5/// This parameter has been deprecated and it will be removed in future Firecracker
6/// release.
7///
8/// The following set of static CPU templates are supported:
9///
10/// | Template | CPU vendor | CPU model |
11/// |----------|------------|-----------|
12/// | C3 | Intel | any |
13/// | T2 | Intel | any |
14/// | T2A | AMD | Milan |
15/// | T2CL | Intel | Cascade Lake or newer |
16/// | T2S | Intel | any |
17/// | V1N1 | ARM | Neoverse V1 |
18///
19#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
20pub struct CPUTemplate(
21 /// default: "None"
22 pub CPUTemplateString,
23);
24
25#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
26pub enum CPUTemplateString {
27 /// CPU vendor | CPU model
28 /// Intel | any
29 #[serde(rename = "C3")]
30 C3,
31 /// Intel | any
32 #[serde(rename = "T2")]
33 T2,
34 /// AMD | Milan
35 #[serde(rename = "T2S")]
36 T2S,
37 /// Intel | Cascade Lake or newer
38 #[serde(rename = "T2CL")]
39 T2CL,
40 /// Intel | any
41 #[serde(rename = "T2A")]
42 T2A,
43 /// ARM | Neoverse V1
44 #[serde(rename = "V1N1")]
45 V1N1,
46 #[default]
47 #[serde(rename = "None")]
48 None,
49}
50
51/// The CPU configuration template defines a set of bit maps as modifiers
52/// of flags accessed by register to be disabled/enabled for the microvm.
53/// For advanved users.
54#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
55pub struct CPUConfig {
56 /// Additional KVM capabilities can be added or existing (built-in) capabilities can
57 /// be removed from the firecracker checks. To add KVM capability to the checklist specify
58 /// decimal number of the corresponding KVM capability. To remove a KVM capability from the
59 /// checklist specify decimal number of the corresponding KVM capability with '!' mark in
60 /// the front. Works on both x86_64 and aarch64.
61 pub kvm_capabilities: Vec<KvmCapabilitiy>,
62
63 /// vCPU features to enable during vCPU initialization. Only for aarch64.
64 pub vcpu_features: Vec<VcpuModifier>,
65
66 /// A collection of CPUIDs to be modified. (x86_64)
67 pub cpuid_modifiers: Vec<CpuIdModifier>,
68
69 /// A collection of model specific registers to be modified. (x86_64)
70 pub msr_modifiers: Vec<MsrModifier>,
71
72 /// A collection of registers to be modified. (aarch64)
73 pub reg_modifiers: Vec<RegModifier>,
74}
75
76/// Examples: ["171", "!172"]
77pub type KvmCapabilitiy = String;
78
79#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
80pub struct VcpuModifier {
81 /// Index into kvm_vcpu_init::features array.
82 /// As of Linux kernel 6.4.10, only value 0 is allowed.
83 pub index: usize,
84
85 /// Bitmap for modifying the 32 bit field in kvm_vcpu_init::features.
86 /// Must be in the format `0b[01x]{1,32}`.
87 /// Corresponding bits will be cleared (`0`), set (`1`) or left intact (`x`). (`_`) can be used as a separator.
88 /// Examples: ["0b11xxxxx"]
89 pub bitmap: String,
90}
91
92/// CPUID modifiers. Only for x86_64.
93#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
94pub struct CpuIdModifier {
95 /// CPUID leaf index (or function). Must be a string containing an integer.
96 /// Examples: ["0x1", "0x2"]
97 pub leaf: String,
98
99 /// CPUID subleaf index (or subfunction). Must be a string containing an integer.
100 /// Examples: ["0x1", "0x2"]
101 pub subleaf: String,
102
103 /// KVM CPUID flags, see https://docs.kernel.org/virt/kvm/api.html#kvm-get-supported-cpuid
104 pub flags: u32,
105
106 /// CPUID register modifiers.
107 pub modifiers: Vec<Modifiers>,
108}
109
110/// CPUID register modifier
111#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
112pub struct Modifiers {
113 /// CPUID register name
114 /// One of ["eax", "ebx", "ecx", "edx"]
115 pub register: ModifierRegisterName,
116
117 /// CPUID register value bitmap.
118 /// Must be in format `0b[01x]{32}`.
119 /// Corresponding bits will be cleared (`0`), set (`1`) or left intact (`x`). (`_`) can be used as a separator.
120 /// Examples: ["0bxxxx000000000011xx00011011110010", "0bxxxxxxxxxxxxx0xx00xx00x0_0000_00xx"]
121 pub bitmap: String,
122}
123
124#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
125pub enum ModifierRegisterName {
126 #[serde(rename = "eax")]
127 EAX,
128 #[serde(rename = "ebx")]
129 EBX,
130 #[serde(rename = "ecx")]
131 ECX,
132 #[serde(rename = "edx")]
133 EDX,
134}
135
136/// MSR modifiers. Only for x86_64.
137#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
138pub struct MsrModifier {
139 /// MSR address/identifier. Must be a string containing an integer.
140 /// Example: ["0x10a"]
141 pub addr: String,
142
143 /// MSR value bitmap.
144 /// Must be in format `0b[01x]{64}`.
145 /// Corresponding bits will be cleared (`0`), set (`1`) or left intact (`x`). (`_`) can be used as a separator.
146 /// Example: ["0bxxxx0000000000000000000000000000000000000000000000000000_11101011"]
147 pub bitmap: String,
148}
149
150#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
151pub struct RegModifier {
152 /// ARM register address/identifier. Must be a string containing an integer. See https://docs.kernel.org/virt/kvm/api.html#kvm-set-one-reg
153 /// Example: ["0x603000000013c020"]
154 pub addr: String,
155
156 /// ARM register value bitmap. Must be in format `0b[01x]{1,128}`. The actual length of the bitmap should be less or equal to the size of the register in bits. Corresponding bits will be cleared (`0`), set (`1`) or left intact (`x`). (`_`) can be used as a separator.
157 /// Example: ["0bxxxxxxxxxxxx_0000_xxxx_xxxx_xxxx_0000_xxxx_xxxx_xxxx_xxxx_xxxx_xxxx_xxxx_xxxx"]
158 pub bitmap: String,
159}