]> git.saurik.com Git - apple/xnu.git/blame - osfmk/machine/pal_hibernate.h
xnu-7195.60.75.tar.gz
[apple/xnu.git] / osfmk / machine / pal_hibernate.h
CommitLineData
1c79356b 1/*
6d2010ae 2 * Copyright (c) 2010 Apple Inc. All rights reserved.
1c79356b 3 *
2d21ac55 4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
0a7de745 5 *
2d21ac55
A
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.
0a7de745 14 *
2d21ac55
A
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
0a7de745 17 *
2d21ac55
A
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
8f6c56a5
A
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2d21ac55
A
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.
0a7de745 25 *
2d21ac55 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
1c79356b 27 */
f427ee49
A
28/**
29 * Platform abstraction layer to support hibernation.
30 */
31
6d2010ae
A
32#ifndef _MACHINE_PAL_HIBERNATE_H
33#define _MACHINE_PAL_HIBERNATE_H
1c79356b 34
f427ee49
A
35#include <sys/cdefs.h>
36
6d2010ae
A
37#if defined (__i386__) || defined(__x86_64__)
38#include "i386/pal_hibernate.h"
5ba3f43e
A
39#elif defined (__arm__)
40//#include "arm/pal_hibernate.h"
f427ee49
A
41#elif defined(__arm64__)
42#include "arm64/pal_hibernate.h"
1c79356b
A
43#else
44#error architecture not supported
45#endif
46
f427ee49
A
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 */
53typedef 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 */
66typedef 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 */
77void __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 */
90uintptr_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 */
98void pal_hib_restore_pal_state(uint32_t *src);
99
100/*!
101 * @function pal_hib_init
102 * @discussion Platform-specific hibernation initialization.
103 */
104void pal_hib_init(void);
105
106/*!
107 * @function pal_hib_write_hook
108 * @discussion Platform-specific callout before the hibernation image is written.
109 */
110void 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 */
121void 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 */
131void 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 */
139void 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 */
148void 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 */
154void 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 */
165void pal_hib_decompress_page(void *src, void *dst, void *scratch, unsigned int compressedSize);
166
167__END_DECLS
168
6d2010ae 169#endif /* _MACHINE_PAL_HIBERNATE_H */