Implement APIs to Take a Snapshot (Compact 2013)

Article
11/09/2017

3/26/2014

Taking a snapshot is a partnership between the OS and the OAL snapshot boot APIs that you implement. These functions must be shared between the boot loader and the OS. You can either create a library that can be shared between the boot loader and the kernel, or you can put your functions in an existing library that can be shared. You must implement the functions shown in this procedure.

To implement APIs to take a snapshot

SnapshotSupport

typedef struct _SnapshotSupport {
    PFN_OEMPrepareSnapshot pfnPrepareSnapshot; // prepare storage for writing snapshot
    PFN_OEMWriteSnapshot   pfnSnapWrite;       // called to write the snapshot
    PFN_OEMTakeCPUSnapshot pfnSnapCPU;         // snap cpu context
    PFN_OEMSnapshotResume  pfnSnapshotResume;  // called when resuming from snapshot
    PFN_OEMCompressSnapshot pfnCompress;       // optional compression function
    PFN_OEMGetSnapshotRegions pfnSnapGetOemRegions; // optional, return OEM specific memory regions
    PFN_OEMReadSnapshot pfnSnapRead;           // optional. Provide to support snapshot paging
    DWORD dwOemData;                           // OEM specific value that is added to snapshot header
} SnapshotSupport, *PSnapshotSupport;

Create an instance of this structure and set the fields to the corresponding addresses of your snapshot boot functions, and then pass that instance to the OS using the OEMGLOBAL->pSnapshotSupport field.

OEMGLOBAL->pSnapshotSupport must be set in your BSP initialization code before you can take or restore a snapshot. Consider initializing the SnapshotSupport structure and associating it with your OEMGLOBAL structure, together with any other initialization that you have to do. This can include preparing the storage where your snapshot image is to be read during OALIoCtlHALPostInit(), which the OS calls after OEM initialization.

OEMGetSnapshotRegions

This optional function is the first function that is called after issuing IOCTL_KLIB_MAKESNAP. You only have to implement this function if you have specific regions of memory that the OS does not automatically include in the snapshot.

You must specify memory regions that you have reserved if you want them included in the snapshot. For example, report memory used for your display buffer, any memory reserved for digital video, the memory for your RAM disk if you have one, the memory used to store configuration parameters that are shared between the boot loader and OS, the memory where CPU specific information such as CPU version information is stored, and so on.

The address space within each individual OEM region described the table returned from this function must be physically contiguous or you will not be able to boot from the snapshot. The regions taken as a whole do not have to be contiguous, but the address space within each individual region must be physically contiguous.

If you implement this function, provide its address in the pfnSnapGetOemRegions member of the SnapshotSupport structure.
OEMTakeCPUSnapshot

This function, typically written in assembly language, saves all of the CPU registers (including control registers) to the memory pointed to by the pCpuContext parameter. Save the state that is required to resume the processor when the system restarts. For example, for ARM processors, include the state for all processor modes such as SVC, SYSTEM, ABORT, UNDEFINE, and so on.

Replace the program counter value that you save with the value that is contained in the dwSnapPC parameter. This will cause the system to resume in OEMSnapshotResume after you restore the CPU context.
OEMCompressSnapshot

This optional function is called by the OS to compress the non-pageable memory included in the snapshot. Compressing the snapshot is optional but may reduce the time that is required to save and restore the snapshot image.

If you choose not to compress the snapshot, you will not need a decompression buffer in your boot loader and the snapshot boot image can be read directly into execute-in-place (XIP) memory.

If you do not implement snapshot paging, all of the memory in the snapshot image will be considered non-pageable. If you support compression, it will be compressed. If you do not support snapshot paging, the whole snapshot image will be loaded during snapshot boot. Compression may be more important to implement if you do not support snapshot paging.

Return false from this function if you choose not to compress the snapshot, or if you fail when trying to do so. The OS will then attempt to save your uncompressed snapshot image to storage.

This function gives you the flexibility to compress the snapshot using your choice of compression algorithms. A sample run-length encoding algorithm that you can use is provided in the boot loader common code. For more information, see Snapshot Boot Sample Code.

The whole buffer is compressed at the same time. When you boot from a compressed snapshot, you can decompress it into a buffer that is smaller than the whole snapshot by decompressing the snapshot one piece at a time. This reduces the amount of memory you have to set aside in your boot loader for decompression. You can also choose to decompress the whole buffer at the same time.

If there is not enough storage to save your snapshot image, execution will continue without taking the snapshot. A fatal error is not generated. You can detect whether the system was able to take the snapshot by examining the return value from IOCTL_KLIB_MAKESNAP or by checking GetSnapshotState for eSnapTaken.
OEMPrepareSnapshot

This function is called by the OS with the cbSnapSize parameter set to the amount of storage that you must have to store the snapshot.

This function is your opportunity to prepare the storage you want to use to store the snapshot. For example, if you are writing the snapshot to NAND flash, you may have to erase it before you can rewrite it to store the snapshot. The amount of storage to prepare is passed to the function in the cbSnapSize parameter.

If you cannot prepare sufficient memory to save the snapshot, return false from this function.
OEMWriteSnapshot

This function is called by the OS to write the snapshot to disk. The snapshot is not written at the same time, but is instead written in pieces.

This function is called multiple times and you should keep writing the snapshot image to your storage at the specified offset from the beginning of the snapshot area until the function is called with the pSnapshot argument set to NULL, which indicates that all of the snapshot image data has been written.

When this function is called with pSnapshot equal to NULL, you can do any housekeeping required to close out your snapshot storage.

Next Steps

Modify the Boot Loader for Snapshot Boot

Share via

Implement APIs to Take a Snapshot (Compact 2013)

To implement APIs to take a snapshot

Next Steps

See Also

Concepts

Other Resources

Additional resources