@@ -21,7 +21,6 @@ static void balloon_page_enqueue_one(struct balloon_dev_info *b_dev_info,
2121 * memory corruption is possible and we should stop execution.
2222 */
2323 BUG_ON (!trylock_page (page ));
24- list_del (& page -> lru );
2524 balloon_page_insert (b_dev_info , page );
2625 unlock_page (page );
2726 __count_vm_event (BALLOON_INFLATE );
@@ -33,8 +32,8 @@ static void balloon_page_enqueue_one(struct balloon_dev_info *b_dev_info,
3332 * @b_dev_info: balloon device descriptor where we will insert a new page to
3433 * @pages: pages to enqueue - allocated using balloon_page_alloc.
3534 *
36- * Driver must call it to properly enqueue a balloon pages before definitively
37- * removing it from the guest system.
35+ * Driver must call this function to properly enqueue balloon pages before
36+ * definitively removing them from the guest system.
3837 *
3938 * Return: number of pages that were enqueued.
4039 */
@@ -47,6 +46,7 @@ size_t balloon_page_list_enqueue(struct balloon_dev_info *b_dev_info,
4746
4847 spin_lock_irqsave (& b_dev_info -> pages_lock , flags );
4948 list_for_each_entry_safe (page , tmp , pages , lru ) {
49+ list_del (& page -> lru );
5050 balloon_page_enqueue_one (b_dev_info , page );
5151 n_pages ++ ;
5252 }
@@ -63,12 +63,13 @@ EXPORT_SYMBOL_GPL(balloon_page_list_enqueue);
6363 * @n_req_pages: number of requested pages.
6464 *
6565 * Driver must call this function to properly de-allocate a previous enlisted
66- * balloon pages before definetively releasing it back to the guest system.
66+ * balloon pages before definitively releasing it back to the guest system.
6767 * This function tries to remove @n_req_pages from the ballooned pages and
6868 * return them to the caller in the @pages list.
6969 *
70- * Note that this function may fail to dequeue some pages temporarily empty due
71- * to compaction isolated pages.
70+ * Note that this function may fail to dequeue some pages even if the balloon
71+ * isn't empty - since the page list can be temporarily empty due to compaction
72+ * of isolated pages.
7273 *
7374 * Return: number of pages that were added to the @pages list.
7475 */
@@ -112,12 +113,13 @@ EXPORT_SYMBOL_GPL(balloon_page_list_dequeue);
112113
113114/*
114115 * balloon_page_alloc - allocates a new page for insertion into the balloon
115- * page list.
116+ * page list.
117+ *
118+ * Driver must call this function to properly allocate a new balloon page.
119+ * Driver must call balloon_page_enqueue before definitively removing the page
120+ * from the guest system.
116121 *
117- * Driver must call it to properly allocate a new enlisted balloon page.
118- * Driver must call balloon_page_enqueue before definitively removing it from
119- * the guest system. This function returns the page address for the recently
120- * allocated page or NULL in the case we fail to allocate a new page this turn.
122+ * Return: struct page for the allocated page or NULL on allocation failure.
121123 */
122124struct page * balloon_page_alloc (void )
123125{
@@ -128,15 +130,17 @@ struct page *balloon_page_alloc(void)
128130EXPORT_SYMBOL_GPL (balloon_page_alloc );
129131
130132/*
131- * balloon_page_enqueue - allocates a new page and inserts it into the balloon
132- * page list.
133- * @b_dev_info: balloon device descriptor where we will insert a new page to
133+ * balloon_page_enqueue - inserts a new page into the balloon page list.
134+ *
135+ * @b_dev_info: balloon device descriptor where we will insert a new page
134136 * @page: new page to enqueue - allocated using balloon_page_alloc.
135137 *
136- * Driver must call it to properly enqueue a new allocated balloon page
137- * before definitively removing it from the guest system.
138- * This function returns the page address for the recently enqueued page or
139- * NULL in the case we fail to allocate a new page this turn.
138+ * Drivers must call this function to properly enqueue a new allocated balloon
139+ * page before definitively removing the page from the guest system.
140+ *
141+ * Drivers must not call balloon_page_enqueue on pages that have been pushed to
142+ * a list with balloon_page_push before removing them with balloon_page_pop. To
143+ * enqueue a list of pages, use balloon_page_list_enqueue instead.
140144 */
141145void balloon_page_enqueue (struct balloon_dev_info * b_dev_info ,
142146 struct page * page )
@@ -151,14 +155,23 @@ EXPORT_SYMBOL_GPL(balloon_page_enqueue);
151155
152156/*
153157 * balloon_page_dequeue - removes a page from balloon's page list and returns
154- * the its address to allow the driver release the page.
158+ * its address to allow the driver to release the page.
155159 * @b_dev_info: balloon device decriptor where we will grab a page from.
156160 *
157- * Driver must call it to properly de-allocate a previous enlisted balloon page
158- * before definetively releasing it back to the guest system.
159- * This function returns the page address for the recently dequeued page or
160- * NULL in the case we find balloon's page list temporarily empty due to
161- * compaction isolated pages.
161+ * Driver must call this function to properly dequeue a previously enqueued page
162+ * before definitively releasing it back to the guest system.
163+ *
164+ * Caller must perform its own accounting to ensure that this
165+ * function is called only if some pages are actually enqueued.
166+ *
167+ * Note that this function may fail to dequeue some pages even if there are
168+ * some enqueued pages - since the page list can be temporarily empty due to
169+ * the compaction of isolated pages.
170+ *
171+ * TODO: remove the caller accounting requirements, and allow caller to wait
172+ * until all pages can be dequeued.
173+ *
174+ * Return: struct page for the dequeued page, or NULL if no page was dequeued.
162175 */
163176struct page * balloon_page_dequeue (struct balloon_dev_info * b_dev_info )
164177{
@@ -171,9 +184,9 @@ struct page *balloon_page_dequeue(struct balloon_dev_info *b_dev_info)
171184 if (n_pages != 1 ) {
172185 /*
173186 * If we are unable to dequeue a balloon page because the page
174- * list is empty and there is no isolated pages, then something
187+ * list is empty and there are no isolated pages, then something
175188 * went out of track and some balloon pages are lost.
176- * BUG() here, otherwise the balloon driver may get stuck into
189+ * BUG() here, otherwise the balloon driver may get stuck in
177190 * an infinite loop while attempting to release all its pages.
178191 */
179192 spin_lock_irqsave (& b_dev_info -> pages_lock , flags );
@@ -224,8 +237,8 @@ int balloon_page_migrate(struct address_space *mapping,
224237
225238 /*
226239 * We can not easily support the no copy case here so ignore it as it
227- * is unlikely to be use with ballon pages. See include/linux/hmm.h for
228- * user of the MIGRATE_SYNC_NO_COPY mode.
240+ * is unlikely to be used with balloon pages. See include/linux/hmm.h
241+ * for a user of the MIGRATE_SYNC_NO_COPY mode.
229242 */
230243 if (mode == MIGRATE_SYNC_NO_COPY )
231244 return - EINVAL ;
0 commit comments