1mod config;
8mod digest;
9mod fsutil;
10mod media_types;
11pub(crate) mod reference;
12mod transport;
13
14use std::path::{Path, PathBuf};
15use std::sync::Arc;
16
17use hyperlight_common::flatbuffer_wrappers::host_function_details::HostFunctionDetails;
18use oci_spec::image::{
19 Descriptor, DescriptorBuilder, ImageIndex, ImageIndexBuilder, ImageManifest,
20 ImageManifestBuilder, MediaType, SCHEMA_VERSION,
21};
22
23use self::config::{
24 Arch, CpuVendor, HostFunction, Hypervisor, MemoryLayout, OciSnapshotConfig, OciSnapshotLayer,
25};
26use self::digest::{Digest256, oci_digest, parse_oci_digest, verify_blob_bytes, verify_blob_file};
27use self::fsutil::{put_blob, put_blob_if_absent, read_bounded, replace_file_atomic};
28use self::media_types::{
29 ANNOTATION_ARCH, ANNOTATION_CPU, ANNOTATION_HYPERVISOR, ANNOTATION_REF_NAME,
30};
31pub(super) use self::media_types::{
32 MT_CONFIG_CURRENT, MT_CONFIG_V1, MT_CONFIG_V2, MT_CONFIG_V3, MT_CONFIG_V4, MT_CONFIG_V5,
33 MT_SNAPSHOT_CURRENT, MT_SNAPSHOT_V2, MT_TRANSPORT_CURRENT, MT_TRANSPORT_V1,
34 SNAPSHOT_ABI_VERSION,
35};
36use self::reference::{OciDigest, OciReference, OciTag};
37use super::memory::{MAX_SNAPSHOT_LAYERS, host_page_size};
38use super::{NextAction, Snapshot, SnapshotBlob, SnapshotMemory};
39use crate::mem::layout::SandboxMemoryLayout;
40use crate::mem::memory_region::MemoryRegionFlags;
41use crate::mem::shared_mem::{ReadonlySharedMemory, SharedMemory};
42
43pub(super) const OCI_LAYOUT_VERSION: &str = "1.0.0";
44
45#[doc(hidden)]
49pub fn host_cpu_vendor_golden_tag() -> Option<&'static str> {
50 CpuVendor::current().golden_tag()
51}
52
53const MAX_JSON_BLOB_SIZE: u64 = 1024 * 1024;
57
58fn check_json_blob_size(what: &str, len: usize) -> crate::Result<()> {
62 if len as u64 > MAX_JSON_BLOB_SIZE {
63 return Err(crate::new_error!(
64 "{} of {} bytes exceeds the {} byte maximum for a snapshot artifact",
65 what,
66 len,
67 MAX_JSON_BLOB_SIZE
68 ));
69 }
70 Ok(())
71}
72
73fn select_manifest<'a>(
80 index: &'a ImageIndex,
81 reference: &OciReference,
82 path: &Path,
83) -> crate::Result<&'a Descriptor> {
84 match reference {
85 OciReference::Tag(tag) => {
86 let mut matching = index.manifests().iter().filter(|d| {
87 d.annotations()
88 .as_ref()
89 .and_then(|a| a.get(ANNOTATION_REF_NAME))
90 .map(|s| s.as_str() == tag.as_str())
91 .unwrap_or(false)
92 });
93 match (matching.next(), matching.next()) {
94 (None, _) => {
95 let known: Vec<&str> = index
96 .manifests()
97 .iter()
98 .filter_map(|d| {
99 d.annotations()
100 .as_ref()
101 .and_then(|a| a.get(ANNOTATION_REF_NAME))
102 .map(|s| s.as_str())
103 })
104 .collect();
105 Err(crate::new_error!(
106 "no manifest tagged {:?} in OCI layout {:?}. Available tags: {:?}",
107 tag.as_str(),
108 path,
109 known
110 ))
111 }
112 (Some(_), Some(_)) => Err(crate::new_error!(
113 "OCI layout {:?} has multiple manifests tagged {:?}; tags must be unique",
114 path,
115 tag.as_str()
116 )),
117 (Some(d), None) => Ok(d),
118 }
119 }
120 OciReference::Digest(digest) => index
121 .manifests()
122 .iter()
123 .find(|d| d.digest().to_string() == digest.as_str())
124 .ok_or_else(|| {
125 crate::new_error!(
126 "no manifest with digest {} in OCI layout {:?}",
127 digest.as_str(),
128 path
129 )
130 }),
131 }
132}
133
134fn read_layout_marker(path: &Path) -> crate::Result<()> {
135 let layout_bytes = read_bounded(&path.join("oci-layout"), MAX_JSON_BLOB_SIZE)
136 .map_err(|e| crate::new_error!("failed to read oci-layout: {}", e))?;
137 let layout_json: serde_json::Value = serde_json::from_slice(&layout_bytes)
138 .map_err(|e| crate::new_error!("oci-layout is not valid JSON: {}", e))?;
139 let v = layout_json
140 .get("imageLayoutVersion")
141 .and_then(|v| v.as_str())
142 .ok_or_else(|| crate::new_error!("oci-layout missing imageLayoutVersion field"))?;
143 if v != OCI_LAYOUT_VERSION {
144 return Err(crate::new_error!(
145 "unsupported OCI image layout version {:?} (expected {:?})",
146 v,
147 OCI_LAYOUT_VERSION
148 ));
149 }
150 Ok(())
151}
152
153fn load_manifest(
154 path: &Path,
155 blobs_dir: &Path,
156 reference: &OciReference,
157 verify_blobs: bool,
158) -> crate::Result<ImageManifest> {
159 let index_bytes = read_bounded(&path.join("index.json"), MAX_JSON_BLOB_SIZE)
160 .map_err(|e| crate::new_error!("failed to read index.json: {}", e))?;
161 let index: ImageIndex = serde_json::from_slice(&index_bytes)
162 .map_err(|e| crate::new_error!("failed to parse index.json: {}", e))?;
163 if index.schema_version() != SCHEMA_VERSION {
164 return Err(crate::new_error!(
165 "unsupported OCI index schemaVersion {} (expected {})",
166 index.schema_version(),
167 SCHEMA_VERSION
168 ));
169 }
170 if let Some(media_type) = index.media_type()
171 && !matches!(media_type, MediaType::ImageIndex)
172 {
173 return Err(crate::new_error!(
174 "OCI index has unexpected media type {} (expected {})",
175 media_type.to_string(),
176 MediaType::ImageIndex.to_string()
177 ));
178 }
179 let manifest_desc = select_manifest(&index, reference, path)?;
180 if !matches!(manifest_desc.media_type(), MediaType::ImageManifest) {
181 return Err(crate::new_error!(
182 "manifest descriptor for {} has unexpected media type {} (expected {})",
183 reference,
184 manifest_desc.media_type().to_string(),
185 MediaType::ImageManifest.to_string()
186 ));
187 }
188 let manifest_bytes = load_blob(
189 "manifest",
190 blobs_dir,
191 manifest_desc,
192 MAX_JSON_BLOB_SIZE,
193 verify_blobs,
194 )?;
195 let manifest: ImageManifest = serde_json::from_slice(&manifest_bytes)
196 .map_err(|e| crate::new_error!("failed to parse OCI manifest JSON: {}", e))?;
197 if manifest.schema_version() != SCHEMA_VERSION {
198 return Err(crate::new_error!(
199 "unsupported OCI manifest schemaVersion {} (expected {})",
200 manifest.schema_version(),
201 SCHEMA_VERSION
202 ));
203 }
204 if let Some(media_type) = manifest.media_type()
205 && !matches!(media_type, MediaType::ImageManifest)
206 {
207 return Err(crate::new_error!(
208 "OCI manifest has unexpected media type {} (expected {})",
209 media_type.to_string(),
210 MediaType::ImageManifest.to_string()
211 ));
212 }
213 Ok(manifest)
214}
215
216fn load_config(
217 blobs_dir: &Path,
218 cfg_desc: &Descriptor,
219 verify_blobs: bool,
220) -> crate::Result<OciSnapshotConfig> {
221 let cfg_bytes = load_blob(
222 "config",
223 blobs_dir,
224 cfg_desc,
225 MAX_JSON_BLOB_SIZE,
226 verify_blobs,
227 )?;
228 let cfg: OciSnapshotConfig = serde_json::from_slice(&cfg_bytes)
229 .map_err(|e| crate::new_error!("failed to parse Hyperlight config JSON: {}", e))?;
230 cfg.validate_for_load()?;
231 Ok(cfg)
232}
233
234fn open_snapshot_blob(blobs_dir: &Path, snap_desc: &Descriptor) -> crate::Result<std::fs::File> {
235 let snap_hex = parse_oci_digest(snap_desc.digest())?;
236 let snap_path = blobs_dir.join(&snap_hex);
237
238 let snap_file = self::fsutil::open_no_follow(&snap_path)?;
239
240 let snap_file_len = snap_file
241 .metadata()
242 .map_err(|e| crate::new_error!("failed to stat snapshot blob: {}", e))?
243 .len();
244 if snap_file_len != snap_desc.size() {
245 return Err(crate::new_error!(
246 "snapshot blob size {} disagrees with OCI descriptor size {}",
247 snap_file_len,
248 snap_desc.size()
249 ));
250 }
251 Ok(snap_file)
252}
253
254fn map_snapshot_blob(
260 snap_file: &std::fs::File,
261 snap_desc: &Descriptor,
262 data_len: usize,
263) -> crate::Result<ReadonlySharedMemory> {
264 let memory = ReadonlySharedMemory::from_file(snap_file, data_len)?;
265 if memory.mem_size() as u64 != snap_desc.size() {
266 return Err(crate::new_error!(
267 "mapped snapshot size ({}) does not match descriptor size ({}); the blob may have changed during loading",
268 memory.mem_size(),
269 snap_desc.size()
270 ));
271 }
272 Ok(memory)
273}
274
275fn load_blob(
277 label: &str,
278 blobs_dir: &Path,
279 descriptor: &Descriptor,
280 max_size: u64,
281 verify_blobs: bool,
282) -> crate::Result<Vec<u8>> {
283 let hex = parse_oci_digest(descriptor.digest())?;
284 let bytes = read_bounded(&blobs_dir.join(&hex), max_size)?;
285 if bytes.len() as u64 != descriptor.size() {
286 return Err(crate::new_error!(
287 "{label} blob size mismatch: descriptor says {}, file is {}",
288 descriptor.size(),
289 bytes.len()
290 ));
291 }
292 if verify_blobs {
293 verify_blob_bytes(label, &bytes, &hex)?;
294 }
295 Ok(bytes)
296}
297
298fn blob_descriptor(media_type: &str, digest: &Digest256, size: usize) -> crate::Result<Descriptor> {
299 DescriptorBuilder::default()
300 .media_type(MediaType::Other(media_type.to_string()))
301 .digest(oci_digest(digest)?)
302 .size(size as u64)
303 .build()
304 .map_err(|e| crate::new_error!("failed to build {media_type} descriptor: {e}"))
305}
306
307impl Snapshot {
308 pub fn save(&self, path: impl AsRef<Path>, tag: &OciTag) -> crate::Result<OciDigest> {
372 let path = path.as_ref();
373
374 let cfg = self.build_config()?;
377 let cfg_bytes = serde_json::to_vec_pretty(&cfg)
378 .map_err(|e| crate::new_error!("failed to serialise config JSON: {}", e))?;
379 check_json_blob_size("config blob", cfg_bytes.len())?;
380
381 match path.parent() {
385 Some(p) if !p.as_os_str().is_empty() => {
386 let parent_meta = std::fs::metadata(p).map_err(|e| {
387 crate::new_error!("save: parent directory {:?} not accessible: {}", p, e)
388 })?;
389 if !parent_meta.is_dir() {
390 return Err(crate::new_error!(
391 "save: parent of {:?} is not a directory",
392 path
393 ));
394 }
395 }
396 _ => {}
397 }
398 match std::fs::create_dir(path) {
399 Ok(()) => {}
400 Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
401 let meta = std::fs::metadata(path)
402 .map_err(|e| crate::new_error!("save: failed to stat {:?}: {}", path, e))?;
403 if !meta.is_dir() {
404 return Err(crate::new_error!(
405 "save: {:?} exists and is not a directory",
406 path
407 ));
408 }
409 }
410 Err(e) => {
411 return Err(crate::new_error!(
412 "save: failed to create layout dir {:?}: {}",
413 path,
414 e
415 ));
416 }
417 }
418
419 let layout_marker = path.join("oci-layout");
424 let marker_existed = layout_marker
425 .try_exists()
426 .map_err(|e| crate::new_error!("save: failed to stat {:?}: {}", layout_marker, e))?;
427 if marker_existed {
428 let bytes = read_bounded(&layout_marker, MAX_JSON_BLOB_SIZE).map_err(|e| {
429 crate::new_error!("save: failed to read existing oci-layout: {}", e)
430 })?;
431 let v: serde_json::Value = serde_json::from_slice(&bytes).map_err(|e| {
432 crate::new_error!("save: existing oci-layout is not valid JSON: {}", e)
433 })?;
434 match v.get("imageLayoutVersion").and_then(|s| s.as_str()) {
435 Some(s) if s == OCI_LAYOUT_VERSION => {}
436 Some(other) => {
437 return Err(crate::new_error!(
438 "save: existing imageLayoutVersion {:?} is unsupported (expected {:?})",
439 other,
440 OCI_LAYOUT_VERSION
441 ));
442 }
443 None => {
444 return Err(crate::new_error!(
445 "save: existing oci-layout is missing imageLayoutVersion"
446 ));
447 }
448 }
449 }
450
451 let index_path = path.join("index.json");
452 let index_existed = index_path
453 .try_exists()
454 .map_err(|e| crate::new_error!("save: failed to stat {:?}: {}", index_path, e))?;
455 let mut manifests: Vec<Descriptor> = if index_existed {
456 let bytes = read_bounded(&index_path, MAX_JSON_BLOB_SIZE).map_err(|e| {
457 crate::new_error!("save: failed to read existing index.json: {}", e)
458 })?;
459 let existing: ImageIndex = serde_json::from_slice(&bytes).map_err(|e| {
460 crate::new_error!(
461 "save: existing index.json is not a valid OCI image index: {}",
462 e
463 )
464 })?;
465 existing.manifests().to_vec()
466 } else {
467 Vec::new()
468 };
469
470 let new_desc = self.write_blobs_and_build_descriptor(path, tag, &cfg, &cfg_bytes)?;
471 let written_digest = OciDigest::from_oci_spec_digest(new_desc.digest());
472
473 manifests.retain(|d| {
477 d.annotations()
478 .as_ref()
479 .and_then(|a| a.get(ANNOTATION_REF_NAME))
480 .map(|s| s.as_str() != tag.as_str())
481 .unwrap_or(true)
482 });
483 manifests.push(new_desc);
484
485 let index = ImageIndexBuilder::default()
486 .schema_version(SCHEMA_VERSION)
487 .media_type(MediaType::ImageIndex)
488 .manifests(manifests)
489 .build()
490 .map_err(|e| crate::new_error!("failed to build OCI index: {}", e))?;
491 let index_bytes = serde_json::to_vec_pretty(&index)
492 .map_err(|e| crate::new_error!("failed to serialise OCI index: {}", e))?;
493 check_json_blob_size("index.json", index_bytes.len())?;
494
495 if !marker_existed {
499 let layout_bytes = serde_json::to_vec(&serde_json::json!({
500 "imageLayoutVersion": OCI_LAYOUT_VERSION,
501 }))
502 .map_err(|e| crate::new_error!("failed to serialise oci-layout: {}", e))?;
503 replace_file_atomic(&layout_marker, &layout_bytes)?;
504 }
505
506 replace_file_atomic(&index_path, &index_bytes)?;
508
509 Ok(written_digest)
510 }
511
512 fn write_blobs_and_build_descriptor(
513 &self,
514 dir: &Path,
515 tag: &OciTag,
516 cfg: &OciSnapshotConfig,
517 cfg_bytes: &[u8],
518 ) -> crate::Result<Descriptor> {
519 let blobs_dir = dir.join("blobs").join("sha256");
520 std::fs::create_dir_all(&blobs_dir).map_err(|e| {
521 crate::new_error!("failed to create OCI blobs dir {:?}: {}", blobs_dir, e)
522 })?;
523
524 let mut descriptors = self
525 .state
526 .memory
527 .blobs()
528 .map(|blob| {
529 let bytes = blob.memory().as_slice();
530 let digest = Digest256::from_bytes(bytes);
531 put_blob_if_absent(&blobs_dir, &digest, bytes)?;
532 blob_descriptor(MT_SNAPSHOT_CURRENT, &digest, bytes.len())
533 })
534 .collect::<crate::Result<Vec<_>>>()?;
535
536 let transport = self.state.virtq.as_ref().ok_or_else(|| {
538 crate::new_error!("initialized snapshot has no canonical transport state")
539 })?;
540 let transport_bytes = transport::encode(&self.state.layout, transport)?;
541 let transport_digest = Digest256::from_bytes(&transport_bytes);
542 put_blob(&blobs_dir, &transport_digest, &transport_bytes)?;
543 descriptors.push(blob_descriptor(
544 MT_TRANSPORT_CURRENT,
545 &transport_digest,
546 transport_bytes.len(),
547 )?);
548
549 let cfg_digest = Digest256::from_bytes(cfg_bytes);
551 put_blob(&blobs_dir, &cfg_digest, cfg_bytes)?;
552
553 let config_descriptor = blob_descriptor(MT_CONFIG_CURRENT, &cfg_digest, cfg_bytes.len())?;
555 let manifest = ImageManifestBuilder::default()
560 .schema_version(SCHEMA_VERSION)
561 .media_type(MediaType::ImageManifest)
562 .artifact_type(MediaType::Other(MT_CONFIG_CURRENT.to_string()))
563 .config(config_descriptor)
564 .layers(descriptors)
565 .build()
566 .map_err(|e| crate::new_error!("failed to build OCI manifest: {}", e))?;
567 let manifest_bytes = serde_json::to_vec_pretty(&manifest)
568 .map_err(|e| crate::new_error!("failed to serialise OCI manifest: {}", e))?;
569 check_json_blob_size("manifest blob", manifest_bytes.len())?;
570 let manifest_digest = Digest256::from_bytes(&manifest_bytes);
571 put_blob(&blobs_dir, &manifest_digest, &manifest_bytes)?;
572
573 let mut anns = std::collections::HashMap::new();
574 anns.insert(ANNOTATION_REF_NAME.to_string(), tag.as_str().to_string());
575 anns.insert(ANNOTATION_ARCH.to_string(), cfg.arch.as_str().to_string());
576 anns.insert(
577 ANNOTATION_HYPERVISOR.to_string(),
578 cfg.hypervisor.as_str().to_string(),
579 );
580 anns.insert(
581 ANNOTATION_CPU.to_string(),
582 cfg.cpu_vendor.as_str().to_string(),
583 );
584 DescriptorBuilder::default()
585 .media_type(MediaType::ImageManifest)
586 .digest(oci_digest(&manifest_digest)?)
587 .size(manifest_bytes.len() as u64)
588 .annotations(anns)
589 .build()
590 .map_err(|e| crate::new_error!("failed to build manifest descriptor: {}", e))
591 }
592
593 fn build_config(&self) -> crate::Result<OciSnapshotConfig> {
594 let (entrypoint_addr, sregs) = match (self.state.next_action, self.state.sregs.as_ref()) {
595 (NextAction::Call(addr), Some(sregs)) => (addr, sregs),
596 (NextAction::Call(_), None) => {
597 return Err(crate::new_error!(
598 "snapshot inconsistent: Call entrypoint must have sregs"
599 ));
600 }
601 (NextAction::Initialise(_), _) => {
602 return Err(crate::new_error!(
603 "pre-init snapshots cannot be persisted. Only a snapshot taken after the guest has run can be saved to disk"
604 ));
605 }
606 #[cfg(test)]
607 (NextAction::None, _) => {
608 return Err(crate::new_error!(
609 "snapshot with NextAction::None cannot be persisted"
610 ));
611 }
612 };
613
614 if self.state.virtq.is_none() {
615 return Err(crate::new_error!(
616 "initialized snapshot has no canonical transport state"
617 ));
618 }
619
620 let host_functions = match &self.state.host_functions.host_functions {
621 Some(v) => v.iter().map(HostFunction::from).collect(),
622 None => Vec::new(),
623 };
624
625 let l = &self.state.layout;
626 Ok(OciSnapshotConfig {
627 hyperlight_version: env!("CARGO_PKG_VERSION").to_string(),
628 arch: Arch::current(),
629 abi_version: SNAPSHOT_ABI_VERSION,
630 hypervisor: Hypervisor::current()
631 .ok_or_else(|| crate::new_error!("no hypervisor available to tag snapshot"))?,
632 cpu_vendor: CpuVendor::current(),
633 layer_alignment: host_page_size(),
634 stack_top_gva: self.state.stack_top_gva,
635 entrypoint_addr,
636 original_entrypoint_addr: self.state.original_entrypoint,
637 sregs: *sregs,
638 #[cfg(target_arch = "x86_64")]
639 msrs: self
640 .state
641 .msrs
642 .as_ref()
643 .ok_or_else(|| crate::new_error!("snapshot has no MSR state"))?
644 .clone(),
645 layout: MemoryLayout {
646 code_size: l.code_size(),
647 code_virt_base: l.get_guest_code_gva() as u64,
648 init_data_size: l.init_data_size(),
649 init_data_permissions: l.init_data_permissions().map(|f| f.bits()),
650 scratch_size: l.get_scratch_size(),
651 g2h_queue_size: l.get_g2h_queue_size(),
652 h2g_queue_size: l.get_h2g_queue_size(),
653 g2h_buffer_size: l.get_g2h_buffer_size(),
654 h2g_buffer_size: l.get_h2g_buffer_size(),
655 g2h_pool_pages: l.get_g2h_pool_pages(),
656 h2g_pool_pages: l.get_h2g_pool_pages(),
657 },
658 layers: self
659 .state
660 .memory
661 .blobs()
662 .map(OciSnapshotLayer::from)
663 .collect(),
664 page_table_layer: self
665 .state
666 .memory
667 .blobs()
668 .position(|blob| Arc::ptr_eq(blob, self.state.memory.page_table_blob()))
669 .ok_or_else(|| crate::new_error!("snapshot page-table blob is missing"))?,
670 host_functions,
671 snapshot_generation: self.state.snapshot_generation,
672 metadata: self.metadata.clone(),
673 })
674 }
675
676 pub fn load(path: impl AsRef<Path>, reference: impl Into<OciReference>) -> crate::Result<Self> {
742 Self::load_inner(path.as_ref(), &reference.into(), false)
743 }
744
745 pub fn checked_load(
758 path: impl AsRef<Path>,
759 reference: impl Into<OciReference>,
760 ) -> crate::Result<Self> {
761 Self::load_inner(path.as_ref(), &reference.into(), true)
762 }
763
764 fn load_inner(
765 path: &Path,
766 reference: &OciReference,
767 verify_blobs: bool,
768 ) -> crate::Result<Self> {
769 let meta = std::fs::metadata(path)
770 .map_err(|e| crate::new_error!("load failed to stat {:?}: {}", path, e))?;
771 if !meta.is_dir() {
772 return Err(crate::new_error!("load path {:?} is not a directory", path));
773 }
774
775 let blobs_dir: PathBuf = path.join("blobs").join("sha256");
776
777 read_layout_marker(path)?;
779
780 let manifest = load_manifest(path, &blobs_dir, reference, verify_blobs)?;
788 let cfg_desc = manifest.config();
789 let cfg_media = cfg_desc.media_type().to_string();
791 match cfg_media.as_str() {
792 MT_CONFIG_V5 => {}
793 MT_CONFIG_V1 | MT_CONFIG_V2 | MT_CONFIG_V3 | MT_CONFIG_V4 => {
794 return Err(crate::new_error!(
795 "snapshot config media type {:?} is incompatible with snapshot ABI {}",
796 cfg_media,
797 SNAPSHOT_ABI_VERSION
798 ));
799 }
800 other => {
801 return Err(crate::new_error!(
802 "unexpected config media type {:?} (supported: {:?})",
803 other,
804 MT_CONFIG_V5
805 ));
806 }
807 }
808 match manifest.artifact_type() {
815 Some(at) if at.to_string() == cfg_media => {}
816 Some(at) => {
817 return Err(crate::new_error!(
818 "OCI manifest artifactType {:?} does not match config media type {:?}",
819 at.to_string(),
820 cfg_media
821 ));
822 }
823 None => {
824 return Err(crate::new_error!(
825 "OCI manifest is missing required artifactType (expected {:?})",
826 cfg_media
827 ));
828 }
829 }
830 let layers = manifest.layers();
831 let (data_descs, tail) = layers.split_at(layers.len().saturating_sub(1));
832 let [transport_desc] = tail else {
833 return Err(crate::new_error!(
834 "expected snapshot layers and one transport layer, found {} layers",
835 layers.len()
836 ));
837 };
838 for snap_desc in data_descs {
839 let snap_media = snap_desc.media_type().to_string();
840 match snap_media.as_str() {
841 MT_SNAPSHOT_V2 => {}
842 other => {
843 return Err(crate::new_error!(
844 "unexpected snapshot layer media type {:?} (supported: {:?})",
845 other,
846 MT_SNAPSHOT_V2
847 ));
848 }
849 }
850 }
851 let transport_media = transport_desc.media_type().to_string();
852 match transport_media.as_str() {
853 MT_TRANSPORT_V1 => {}
854 other => {
855 return Err(crate::new_error!(
856 "unexpected transport layer media type {:?} (supported: {:?})",
857 other,
858 MT_TRANSPORT_V1
859 ));
860 }
861 }
862
863 let cfg = load_config(&blobs_dir, cfg_desc, verify_blobs)?;
865 let host_page = crate::mem::layout::SandboxMemoryLayout::host_page_size();
868 if !cfg.layout.scratch_size.is_multiple_of(host_page) {
869 return Err(crate::new_error!(
870 "snapshot scratch size {} is not a multiple of this host's {host_page}-byte pages",
871 cfg.layout.scratch_size
872 ));
873 }
874 if cfg.layers.len() > MAX_SNAPSHOT_LAYERS + 1 {
877 return Err(crate::new_error!(
878 "snapshot has {} data layers, limit is {}",
879 cfg.layers.len(),
880 MAX_SNAPSHOT_LAYERS + 1
881 ));
882 }
883 if data_descs.len() != cfg.layers.len() {
884 return Err(crate::new_error!(
885 "expected {} snapshot layers and one transport layer, found {} layers",
886 cfg.layers.len(),
887 layers.len()
888 ));
889 }
890 if cfg.page_table_layer >= cfg.layers.len() {
891 return Err(crate::new_error!(
892 "snapshot page_table_layer {} is out of range",
893 cfg.page_table_layer
894 ));
895 }
896
897 let data_space = hyperlight_common::layout::scratch_base_gpa(cfg.layout.scratch_size)
902 .saturating_sub(SandboxMemoryLayout::BASE_ADDRESS as u64);
903 let mut data_bytes = 0u64;
904 for (index, (layer, desc)) in cfg.layers.iter().zip(data_descs).enumerate() {
905 if layer.data_len == 0 && index != cfg.page_table_layer {
906 return Err(crate::new_error!("snapshot layer {} has no data", index));
907 }
908 let blob_len = layer
909 .data_len
910 .checked_add(layer.page_table_len)
911 .filter(|_| layer.page_table_len <= SandboxMemoryLayout::MAX_MEMORY_SIZE)
912 .and_then(|len| len.checked_next_multiple_of(host_page_size()));
913 if blob_len.is_none_or(|len| len as u64 != desc.size()) {
914 return Err(crate::new_error!(
915 "snapshot layer {} size {} does not match its data and page-table lengths",
916 index,
917 desc.size()
918 ));
919 }
920 data_bytes = data_bytes
921 .checked_add(layer.data_len as u64)
922 .filter(|bytes| *bytes <= data_space)
923 .ok_or_else(|| {
924 crate::new_error!(
925 "snapshot data exceeds the {} bytes below scratch",
926 data_space
927 )
928 })?;
929 }
930
931 let mut snap_files = data_descs
935 .iter()
936 .map(|desc| open_snapshot_blob(&blobs_dir, desc))
937 .collect::<crate::Result<Vec<_>>>()?;
938 let transport_bytes = load_blob(
939 "transport",
940 &blobs_dir,
941 transport_desc,
942 transport::MAX_BLOB_SIZE,
943 verify_blobs,
944 )?;
945
946 let mut sbox_cfg = crate::sandbox::SandboxConfiguration::default();
948 sbox_cfg.set_scratch_size(cfg.layout.scratch_size);
949 sbox_cfg.set_g2h_queue_size(cfg.layout.g2h_queue_size);
950 sbox_cfg.set_h2g_queue_size(cfg.layout.h2g_queue_size);
951 sbox_cfg.set_g2h_buffer_size(cfg.layout.g2h_buffer_size);
952 sbox_cfg.set_h2g_buffer_size(cfg.layout.h2g_buffer_size);
953 sbox_cfg.set_g2h_pool_pages(cfg.layout.g2h_pool_pages);
954 sbox_cfg.set_h2g_pool_pages(cfg.layout.h2g_pool_pages);
955 let init_data_perms = match cfg.layout.init_data_permissions {
956 None => None,
957 Some(bits) => Some(MemoryRegionFlags::from_bits(bits).ok_or_else(|| {
958 crate::new_error!(
959 "snapshot init_data_permissions {:#x} contains unknown flag bits",
960 bits
961 )
962 })?),
963 };
964 let mut layout = SandboxMemoryLayout::new(
965 sbox_cfg,
966 cfg.layout.code_size,
967 cfg.layout.init_data_size,
968 init_data_perms,
969 )?;
970 let code_gva = if cfg.layout.code_virt_base == 0 {
971 layout.get_guest_code_gpa() as u64
972 } else {
973 cfg.layout.code_virt_base
974 };
975 layout.set_code_gva(code_gva)?;
976 layout.ensure_page_tables_fit(cfg.layers[cfg.page_table_layer].page_table_len)?;
977
978 let virtq = transport::decode(&layout, &transport_bytes)?;
979
980 let scratch_base = hyperlight_common::layout::scratch_base_gpa(layout.get_scratch_size());
991 let blobs = cfg
992 .layers
993 .iter()
994 .zip(data_descs)
995 .zip(&snap_files)
996 .map(|((layer, desc), file)| {
997 Ok(Arc::new(SnapshotBlob::new(
998 map_snapshot_blob(file, desc, layer.data_len)?,
999 layer.gpa_start,
1000 layer.page_table_len,
1001 scratch_base,
1002 )?))
1003 })
1004 .collect::<crate::Result<Vec<_>>>()?;
1005 let page_tables = blobs[cfg.page_table_layer].clone();
1006 let data_layers = blobs
1007 .into_iter()
1008 .filter(|blob| blob.data_len() > 0)
1009 .collect();
1010 let memory = Arc::new(SnapshotMemory::new(data_layers, page_tables)?);
1011 if verify_blobs {
1014 for (desc, file) in data_descs.iter().zip(&mut snap_files) {
1015 verify_blob_file("snapshot", file, &parse_oci_digest(desc.digest())?)?;
1016 }
1017 }
1018
1019 let required_memory_size = layout.get_memory_size()?;
1023 if memory.gpa_span_len() < required_memory_size {
1024 return Err(crate::new_error!(
1025 "snapshot GPA span ({}) is smaller than the layout size ({})",
1026 memory.gpa_span_len(),
1027 required_memory_size
1028 ));
1029 }
1030
1031 let next_action = NextAction::Call(cfg.entrypoint_addr);
1033
1034 let snapshot_generation = cfg.snapshot_generation;
1036 let host_funcs_vec: Vec<
1037 hyperlight_common::flatbuffer_wrappers::host_function_definition::HostFunctionDefinition,
1038 > = cfg.host_functions.into_iter().map(Into::into).collect();
1039 let host_functions = if host_funcs_vec.is_empty() {
1040 HostFunctionDetails {
1041 host_functions: None,
1042 }
1043 } else {
1044 HostFunctionDetails {
1045 host_functions: Some(host_funcs_vec),
1046 }
1047 };
1048
1049 Ok(Snapshot {
1050 state: std::sync::Arc::new(super::SnapshotState {
1051 layout,
1052 memory,
1053 load_info: crate::mem::exe::LoadInfo::dummy(),
1054 stack_top_gva: cfg.stack_top_gva,
1055 sregs: Some(cfg.sregs),
1056 #[cfg(target_arch = "x86_64")]
1057 msrs: Some(cfg.msrs),
1058 next_action,
1059 original_entrypoint: cfg.original_entrypoint_addr,
1060 snapshot_generation,
1061 host_functions,
1062 virtq: Some(virtq),
1063 }),
1064 metadata: cfg.metadata,
1065 })
1066 }
1067}