1 /* 2 * Copyright (c) 2010 Apple Inc. All rights reserved. 3 * 4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. The rights granted to you under the License 10 * may not be used to create, or enable the creation or redistribution of, 11 * unlawful or unlicensed copies of an Apple operating system, or to 12 * circumvent, violate, or enable the circumvention or violation of, any 13 * terms of an Apple operating system software license agreement. 14 * 15 * Please obtain a copy of the License at 16 * http://www.opensource.apple.com/apsl/ and read it before using this file. 17 * 18 * The Original Code and all software distributed under the License are 19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23 * Please see the License for the specific language governing rights and 24 * limitations under the License. 25 * 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ 27 */ 28 /** 29 * Platform abstraction layer to support hibernation. 30 */ 31 32 #ifndef _MACHINE_PAL_HIBERNATE_H 33 #define _MACHINE_PAL_HIBERNATE_H 34 35 #include <sys/cdefs.h> 36 37 #if defined (__i386__) || defined(__x86_64__) 38 #include "i386/pal_hibernate.h" 39 #elif defined (__arm__) 40 //#include "arm/pal_hibernate.h" 41 #elif defined(__arm64__) 42 #include "arm64/pal_hibernate.h" 43 #else 44 #error architecture not supported 45 #endif 46 47 __BEGIN_DECLS 48 49 /*! 50 * @typedef pal_hib_restore_stage_t 51 * @discussion hibernate_kernel_entrypoint restores data in multiple stages; this enum defines those stages. 52 */ 53 typedef enum { 54 pal_hib_restore_stage_dram_pages = 0, 55 pal_hib_restore_stage_preview_pages = 1, 56 pal_hib_restore_stage_handoff_data = 2, 57 } pal_hib_restore_stage_t; 58 59 /*! 60 * @typedef pal_hib_ctx_t 61 * @discussion This type is used to pass context between pal_hib_resume_init, pal_hib_restored_page, and 62 * pal_hib_patchup during hibernation resume. The context is declared on the stack in 63 * hibernate_kernel_entrypoint, so it should be relatively small. During pal_hib_resume_init(), 64 * additional memory can be allocated with hibernate_page_list_grab if necessary. 65 */ 66 typedef struct pal_hib_ctx pal_hib_ctx_t; 67 68 /*! 69 * @function __hib_assert 70 * @discussion Called when a fatal assertion has been detected during hibernation. Logs the 71 * expression string and loops indefinitely. 72 * 73 * @param file The source file in which the failed assertion occurred 74 * @param line The line number at which the failed assertion occurred 75 * @param expression A string describing the failed assertion 76 */ 77 void __hib_assert(const char *file, int line, const char *expression) __attribute__((noreturn)); 78 #define HIB_ASSERT(ex) \ 79 (__builtin_expect(!!((ex)), 1L) ? (void)0 : __hib_assert(__FILE__, __LINE__, # ex)) 80 81 /*! 82 * @function pal_hib_map 83 * @discussion Given a map type and a physical address, return the corresponding virtual address. 84 * 85 * @param virt Which memory region to access 86 * @param phys The physical address to access 87 * 88 * @result The virtual address corresponding to this physical address. 89 */ 90 uintptr_t pal_hib_map(pal_hib_map_type_t virt, uint64_t phys); 91 92 /*! 93 * @function pal_hib_restore_pal_state 94 * @discussion Callout to the platform abstraction layer to restore platform-specific data. 95 * 96 * @param src Pointer to platform-specific data 97 */ 98 void pal_hib_restore_pal_state(uint32_t *src); 99 100 /*! 101 * @function pal_hib_init 102 * @discussion Platform-specific hibernation initialization. 103 */ 104 void pal_hib_init(void); 105 106 /*! 107 * @function pal_hib_write_hook 108 * @discussion Platform-specific callout before the hibernation image is written. 109 */ 110 void pal_hib_write_hook(void); 111 112 /*! 113 * @function pal_hib_resume_init 114 * @discussion Initialize the platform-specific hibernation resume context. Additional memory can 115 * be allocated with hibernate_page_list_grab if necessary 116 * 117 * @param palHibCtx Pointer to platform-specific hibernation resume context 118 * @param map map argument that can be passed to hibernate_page_list_grab 119 * @param nextFree nextFree argument that can be passed to hibernate_page_list_grab 120 */ 121 void pal_hib_resume_init(pal_hib_ctx_t *palHibCtx, hibernate_page_list_t *map, uint32_t *nextFree); 122 123 /*! 124 * @function pal_hib_restored_page 125 * @discussion Inform the platform abstraction layer of a page that will be restored. 126 * 127 * @param palHibCtx Pointer to platform-specific hibernation resume context 128 * @param stage The stage of hibernation resume during which this page will be resumed 129 * @param ppnum The page number of the page that will be resumed. 130 */ 131 void pal_hib_restored_page(pal_hib_ctx_t *palHibCtx, pal_hib_restore_stage_t stage, ppnum_t ppnum); 132 133 /*! 134 * @function pal_hib_patchup 135 * @discussion Allow the platform abstraction layer to perform post-restore fixups. 136 * 137 * @param palHibCtx Pointer to platform-specific hibernation resume context 138 */ 139 void pal_hib_patchup(pal_hib_ctx_t *palHibCtx); 140 141 /*! 142 * @function pal_hib_teardown_pmap_structs 143 * @discussion Platform-specific function to return a range of memory that doesn't need to be saved during hibernation. 144 * 145 * @param unneeded_start Out parameter: the beginning of the unneeded range 146 * @param unneeded_end Out parameter: the end of the unneeded range 147 */ 148 void pal_hib_teardown_pmap_structs(addr64_t *unneeded_start, addr64_t *unneeded_end); 149 150 /*! 151 * @function pal_hib_rebuild_pmap_structs 152 * @discussion Platform-specific function to fix up the teardown done by pal_hib_teardown_pmap_structs. 153 */ 154 void pal_hib_rebuild_pmap_structs(void); 155 156 /*! 157 * @function pal_hib_decompress_page 158 * @discussion Decompress a page of memory using WKdm 159 * 160 * @param src The compressed data 161 * @param dst A page-sized buffer to decompress into; must be page aligned 162 * @param scratch A page-sized scratch buffer to use during decompression 163 * @param compressedSize The number of bytes to decompress 164 */ 165 void pal_hib_decompress_page(void *src, void *dst, void *scratch, unsigned int compressedSize); 166 167 __END_DECLS 168 169 #endif /* _MACHINE_PAL_HIBERNATE_H */ 170