]> git.saurik.com Git - apple/xnu.git/blob - osfmk/machine/pal_hibernate.h
xnu-7195.60.75.tar.gz
[apple/xnu.git] / osfmk / machine / pal_hibernate.h
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 */