1 /*
2  * include/linux/balloon_compaction.h
3  *
4  * Common interface definitions for making balloon pages movable by compaction.
5  *
6  * Despite being perfectly possible to perform ballooned pages migration, they
7  * make a special corner case to compaction scans because balloon pages are not
8  * enlisted at any LRU list like the other pages we do compact / migrate.
9  *
10  * As the page isolation scanning step a compaction thread does is a lockless
11  * procedure (from a page standpoint), it might bring some racy situations while
12  * performing balloon page compaction. In order to sort out these racy scenarios
13  * and safely perform balloon's page compaction and migration we must, always,
14  * ensure following these three simple rules:
15  *
16  *   i. when updating a balloon's page ->mapping element, strictly do it under
17  *      the following lock order, independently of the far superior
18  *      locking scheme (lru_lock, balloon_lock):
19  *	    +-page_lock(page);
20  *	      +--spin_lock_irq(&b_dev_info->pages_lock);
21  *	            ... page->mapping updates here ...
22  *
23  *  ii. before isolating or dequeueing a balloon page from the balloon device
24  *      pages list, the page reference counter must be raised by one and the
25  *      extra refcount must be dropped when the page is enqueued back into
26  *      the balloon device page list, thus a balloon page keeps its reference
27  *      counter raised only while it is under our special handling;
28  *
29  * iii. after the lockless scan step have selected a potential balloon page for
30  *      isolation, re-test the PageBalloon mark and the PagePrivate flag
31  *      under the proper page lock, to ensure isolating a valid balloon page
32  *      (not yet isolated, nor under release procedure)
33  *
34  *  iv. isolation or dequeueing procedure must clear PagePrivate flag under
35  *      page lock together with removing page from balloon device page list.
36  *
37  * The functions provided by this interface are placed to help on coping with
38  * the aforementioned balloon page corner case, as well as to ensure the simple
39  * set of exposed rules are satisfied while we are dealing with balloon pages
40  * compaction / migration.
41  *
42  * Copyright (C) 2012, Red Hat, Inc.  Rafael Aquini <[email protected]>
43  */
44 #ifndef _LINUX_BALLOON_COMPACTION_H
45 #define _LINUX_BALLOON_COMPACTION_H
46 #include <linux/pagemap.h>
47 #include <linux/page-flags.h>
48 #include <linux/migrate.h>
49 #include <linux/gfp.h>
50 #include <linux/err.h>
51 
52 /*
53  * Balloon device information descriptor.
54  * This struct is used to allow the common balloon compaction interface
55  * procedures to find the proper balloon device holding memory pages they'll
56  * have to cope for page compaction / migration, as well as it serves the
57  * balloon driver as a page book-keeper for its registered balloon devices.
58  */
59 struct balloon_dev_info {
60 	unsigned long isolated_pages;	/* # of isolated pages for migration */
61 	spinlock_t pages_lock;		/* Protection to pages list */
62 	struct list_head pages;		/* Pages enqueued & handled to Host */
63 	int (*migratepage)(struct balloon_dev_info *, struct page *newpage,
64 			struct page *page, enum migrate_mode mode);
65 };
66 
67 extern struct page *balloon_page_enqueue(struct balloon_dev_info *b_dev_info);
68 extern struct page *balloon_page_dequeue(struct balloon_dev_info *b_dev_info);
69 
70 static inline void balloon_devinfo_init(struct balloon_dev_info *balloon)
71 {
72 	balloon->isolated_pages = 0;
73 	spin_lock_init(&balloon->pages_lock);
74 	INIT_LIST_HEAD(&balloon->pages);
75 	balloon->migratepage = NULL;
76 }
77 
78 #ifdef CONFIG_BALLOON_COMPACTION
79 extern bool balloon_page_isolate(struct page *page);
80 extern void balloon_page_putback(struct page *page);
81 extern int balloon_page_migrate(struct page *newpage,
82 				struct page *page, enum migrate_mode mode);
83 
84 /*
85  * __is_movable_balloon_page - helper to perform @page PageBalloon tests
86  */
87 static inline bool __is_movable_balloon_page(struct page *page)
88 {
89 	return PageBalloon(page);
90 }
91 
92 /*
93  * balloon_page_movable - test PageBalloon to identify balloon pages
94  *			  and PagePrivate to check that the page is not
95  *			  isolated and can be moved by compaction/migration.
96  *
97  * As we might return false positives in the case of a balloon page being just
98  * released under us, this need to be re-tested later, under the page lock.
99  */
100 static inline bool balloon_page_movable(struct page *page)
101 {
102 	return PageBalloon(page) && PagePrivate(page);
103 }
104 
105 /*
106  * isolated_balloon_page - identify an isolated balloon page on private
107  *			   compaction/migration page lists.
108  */
109 static inline bool isolated_balloon_page(struct page *page)
110 {
111 	return PageBalloon(page);
112 }
113 
114 /*
115  * balloon_page_insert - insert a page into the balloon's page list and make
116  *			 the page->private assignment accordingly.
117  * @balloon : pointer to balloon device
118  * @page    : page to be assigned as a 'balloon page'
119  *
120  * Caller must ensure the page is locked and the spin_lock protecting balloon
121  * pages list is held before inserting a page into the balloon device.
122  */
123 static inline void balloon_page_insert(struct balloon_dev_info *balloon,
124 				       struct page *page)
125 {
126 	__SetPageBalloon(page);
127 	SetPagePrivate(page);
128 	set_page_private(page, (unsigned long)balloon);
129 	list_add(&page->lru, &balloon->pages);
130 }
131 
132 /*
133  * balloon_page_delete - delete a page from balloon's page list and clear
134  *			 the page->private assignement accordingly.
135  * @page    : page to be released from balloon's page list
136  *
137  * Caller must ensure the page is locked and the spin_lock protecting balloon
138  * pages list is held before deleting a page from the balloon device.
139  */
140 static inline void balloon_page_delete(struct page *page)
141 {
142 	__ClearPageBalloon(page);
143 	set_page_private(page, 0);
144 	if (PagePrivate(page)) {
145 		ClearPagePrivate(page);
146 		list_del(&page->lru);
147 	}
148 }
149 
150 /*
151  * balloon_page_device - get the b_dev_info descriptor for the balloon device
152  *			 that enqueues the given page.
153  */
154 static inline struct balloon_dev_info *balloon_page_device(struct page *page)
155 {
156 	return (struct balloon_dev_info *)page_private(page);
157 }
158 
159 static inline gfp_t balloon_mapping_gfp_mask(void)
160 {
161 	return GFP_HIGHUSER_MOVABLE;
162 }
163 
164 #else /* !CONFIG_BALLOON_COMPACTION */
165 
166 static inline void balloon_page_insert(struct balloon_dev_info *balloon,
167 				       struct page *page)
168 {
169 	__SetPageBalloon(page);
170 	list_add(&page->lru, &balloon->pages);
171 }
172 
173 static inline void balloon_page_delete(struct page *page)
174 {
175 	__ClearPageBalloon(page);
176 	list_del(&page->lru);
177 }
178 
179 static inline bool __is_movable_balloon_page(struct page *page)
180 {
181 	return false;
182 }
183 
184 static inline bool balloon_page_movable(struct page *page)
185 {
186 	return false;
187 }
188 
189 static inline bool isolated_balloon_page(struct page *page)
190 {
191 	return false;
192 }
193 
194 static inline bool balloon_page_isolate(struct page *page)
195 {
196 	return false;
197 }
198 
199 static inline void balloon_page_putback(struct page *page)
200 {
201 	return;
202 }
203 
204 static inline int balloon_page_migrate(struct page *newpage,
205 				struct page *page, enum migrate_mode mode)
206 {
207 	return 0;
208 }
209 
210 static inline gfp_t balloon_mapping_gfp_mask(void)
211 {
212 	return GFP_HIGHUSER;
213 }
214 
215 #endif /* CONFIG_BALLOON_COMPACTION */
216 #endif /* _LINUX_BALLOON_COMPACTION_H */
217