Re: [Qemu-devel] [PATCH 01/51] ram: Update all functions comments

[Dr. David Alan Gilbert]

* Juan Quintela (address@hidden) wrote:
> Added doc comments for existing functions comment and rewrite them in
> a common style.
> 
> Signed-off-by: Juan Quintela <address@hidden>
> ---
>  migration/ram.c | 348 
> ++++++++++++++++++++++++++++++++++++--------------------
>  1 file changed, 227 insertions(+), 121 deletions(-)
> 
> diff --git a/migration/ram.c b/migration/ram.c
> index de1e0a3..76f1fc4 100644
> --- a/migration/ram.c
> +++ b/migration/ram.c
> @@ -96,11 +96,17 @@ static void XBZRLE_cache_unlock(void)
>          qemu_mutex_unlock(&XBZRLE.lock);
>  }
>  
> -/*
> - * called from qmp_migrate_set_cache_size in main thread, possibly while
> - * a migration is in progress.
> - * A running migration maybe using the cache and might finish during this
> - * call, hence changes to the cache are protected by XBZRLE.lock().
> +/**
> + * xbzrle_cache_resize: resize the xbzrle cache
> + *
> + * This function is called from qmp_migrate_set_cache_size in main
> + * thread, possibly while a migration is in progress.  A running
> + * migration may be using the cache and might finish during this call,
> + * hence changes to the cache are protected by XBZRLE.lock().
> + *
> + * Returns the new_size or negative in case of error.
> + *
> + * @new_size: new cache size
>   */
>  int64_t xbzrle_cache_resize(int64_t new_size)
>  {
> @@ -323,6 +329,7 @@ static inline void terminate_compression_threads(void)
>      int idx, thread_count;
>  
>      thread_count = migrate_compress_threads();
> +
>      for (idx = 0; idx < thread_count; idx++) {
>          qemu_mutex_lock(&comp_param[idx].mutex);
>          comp_param[idx].quit = true;
> @@ -383,11 +390,11 @@ void migrate_compress_threads_create(void)
>  }
>  
>  /**
> - * save_page_header: Write page header to wire
> + * save_page_header: write page header to wire
>   *
>   * If this is the 1st block, it also writes the block identification
>   *
> - * Returns: Number of bytes written
> + * Returns the number of bytes written

Do the doc tools recognise that to pick up the explanation
for the return value?

>   *
>   * @f: QEMUFile where to send the data
>   * @block: block that contains the page we want to send
> @@ -410,11 +417,14 @@ static size_t save_page_header(QEMUFile *f, RAMBlock 
> *block, ram_addr_t offset)
>      return size;
>  }
>  
> -/* Reduce amount of guest cpu execution to hopefully slow down memory writes.
> - * If guest dirty memory rate is reduced below the rate at which we can
> - * transfer pages to the destination then we should be able to complete
> - * migration. Some workloads dirty memory way too fast and will not 
> effectively
> - * converge, even with auto-converge.
> +/**
> + * mig_throotle_guest_down: throotle down the guest

one 'o'

> + *
> + * Reduce amount of guest cpu execution to hopefully slow down memory
> + * writes. If guest dirty memory rate is reduced below the rate at
> + * which we can transfer pages to the destination then we should be
> + * able to complete migration. Some workloads dirty memory way too
> + * fast and will not effectively converge, even with auto-converge.
>   */
>  static void mig_throttle_guest_down(void)
>  {
> @@ -431,11 +441,16 @@ static void mig_throttle_guest_down(void)
>      }
>  }
>  
> -/* Update the xbzrle cache to reflect a page that's been sent as all 0.
> +/**
> + * xbzrle_cache_zero_page: insert a zero page in the XBZRLE cache
> + *
> + * @current_addr: address for the zero page
> + *
> + * Update the xbzrle cache to reflect a page that's been sent as all 0.
>   * The important thing is that a stale (not-yet-0'd) page be replaced
>   * by the new data.
>   * As a bonus, if the page wasn't in the cache it gets added so that
> - * when a small write is made into the 0'd page it gets XBZRLE sent
> + * when a small write is made into the 0'd page it gets XBZRLE sent.
>   */
>  static void xbzrle_cache_zero_page(ram_addr_t current_addr)
>  {
> @@ -459,8 +474,8 @@ static void xbzrle_cache_zero_page(ram_addr_t 
> current_addr)
>   *          -1 means that xbzrle would be longer than normal
>   *
>   * @f: QEMUFile where to send the data
> - * @current_data:
> - * @current_addr:
> + * @current_data: contents of the page

That's wrong.  The point of current_data is that it gets updated by this
function to point to the cache page whenever the data ends up in the cache.
It's important then that the caller uses that pointer to save the data to
disk/network rather than the original pointer, since the data that's saved
must exactly match the cache contents even if the guest is still writing to it.

> + * @current_addr: addr of the page
>   * @block: block that contains the page we want to send
>   * @offset: offset inside the block for the page
>   * @last_stage: if we are at the completion stage
> @@ -530,13 +545,17 @@ static int save_xbzrle_page(QEMUFile *f, uint8_t 
> **current_data,
>      return 1;
>  }
>  
> -/* Called with rcu_read_lock() to protect migration_bitmap
> - * rb: The RAMBlock  to search for dirty pages in
> - * start: Start address (typically so we can continue from previous page)
> - * ram_addr_abs: Pointer into which to store the address of the dirty page
> - *               within the global ram_addr space
> +/**
> + * migration_bitmap_find_dirty: find the next drity page from start

Typo 'drity'

>   *
> - * Returns: byte offset within memory region of the start of a dirty page
> + * Called with rcu_read_lock() to protect migration_bitmap
> + *
> + * Returns the byte offset within memory region of the start of a dirty page
> + *
> + * @rb: RAMBlock where to search for dirty pages
> + * @start: starting address (typically so we can continue from previous page)
> + * @ram_addr_abs: pointer into which to store the address of the dirty page
> + *                within the global ram_addr space
>   */
>  static inline
>  ram_addr_t migration_bitmap_find_dirty(RAMBlock *rb,
> @@ -600,10 +619,14 @@ static void migration_bitmap_sync_init(void)
>      iterations_prev = 0;
>  }
>  
> -/* Returns a summary bitmap of the page sizes of all RAMBlocks;
> - * for VMs with just normal pages this is equivalent to the
> - * host page size.  If it's got some huge pages then it's the OR
> - * of all the different page sizes.
> +/**
> + * ram_pagesize_summary: calculate all the pagesizes of a VM
> + *
> + * Returns a summary bitmap of the page sizes of all RAMBlocks
> + *
> + * For VMs with just normal pages this is equivalent to the host page
> + * size. If it's got some huge pages then it's the OR of all the
> + * different page sizes.
>   */
>  uint64_t ram_pagesize_summary(void)
>  {
> @@ -693,9 +716,9 @@ static void migration_bitmap_sync(void)
>  }
>  
>  /**
> - * save_zero_page: Send the zero page to the stream
> + * save_zero_page: send the zero page to the stream
>   *
> - * Returns: Number of pages written.
> + * Returns the number of pages written.
>   *
>   * @f: QEMUFile where to send the data
>   * @block: block that contains the page we want to send
> @@ -731,14 +754,14 @@ static void ram_release_pages(MigrationState *ms, const 
> char *block_name,
>  }
>  
>  /**
> - * ram_save_page: Send the given page to the stream
> + * ram_save_page: send the given page to the stream
>   *
> - * Returns: Number of pages written.
> + * Returns the number of pages written.
>   *          < 0 - error
>   *          >=0 - Number of pages written - this might legally be 0
>   *                if xbzrle noticed the page was the same.
>   *
> - * @ms: The current migration state.
> + * @ms: current migration state
>   * @f: QEMUFile where to send the data
>   * @block: block that contains the page we want to send
>   * @offset: offset inside the block for the page
> @@ -921,9 +944,9 @@ static int compress_page_with_multi_thread(QEMUFile *f, 
> RAMBlock *block,
>  /**
>   * ram_save_compressed_page: compress the given page and send it to the 
> stream
>   *
> - * Returns: Number of pages written.
> + * Returns the number of pages written.
>   *
> - * @ms: The current migration state.
> + * @ms: current migration state
>   * @f: QEMUFile where to send the data
>   * @block: block that contains the page we want to send
>   * @offset: offset inside the block for the page
> @@ -1000,17 +1023,17 @@ static int ram_save_compressed_page(MigrationState 
> *ms, QEMUFile *f,
>      return pages;
>  }
>  
> -/*
> - * Find the next dirty page and update any state associated with
> - * the search process.
> +/**
> + * find_dirty_block: find the next dirty page and update any state
> + * associated with the search process.
>   *
> - * Returns: True if a page is found
> + * Returns if a page is found
>   *
> - * @f: Current migration stream.
> - * @pss: Data about the state of the current dirty page scan.
> - * @*again: Set to false if the search has scanned the whole of RAM
> - * *ram_addr_abs: Pointer into which to store the address of the dirty page
> - *               within the global ram_addr space
> + * @f: QEMUFile where to send the data
> + * @pss: data about the state of the current dirty page scan
> + * @again: set to false if the search has scanned the whole of RAM
> + * @ram_addr_abs: pointer into which to store the address of the dirty page
> + *                within the global ram_addr space
>   */
>  static bool find_dirty_block(QEMUFile *f, PageSearchStatus *pss,
>                               bool *again, ram_addr_t *ram_addr_abs)
> @@ -1055,13 +1078,17 @@ static bool find_dirty_block(QEMUFile *f, 
> PageSearchStatus *pss,
>      }
>  }
>  
> -/*
> +/**
> + * unqueue_page: gets a page of the queue
> + *
>   * Helper for 'get_queued_page' - gets a page off the queue
> - *      ms:      MigrationState in
> - * *offset:      Used to return the offset within the RAMBlock
> - * ram_addr_abs: global offset in the dirty/sent bitmaps
>   *
> - * Returns:      block (or NULL if none available)
> + * Returns the block of the page (or NULL if none available)
> + *
> + * @ms: current migration state
> + * @offset: used to return the offset within the RAMBlock
> + * @ram_addr_abs: pointer into which to store the address of the dirty page
> + *                within the global ram_addr space
>   */
>  static RAMBlock *unqueue_page(MigrationState *ms, ram_addr_t *offset,
>                                ram_addr_t *ram_addr_abs)
> @@ -1091,15 +1118,17 @@ static RAMBlock *unqueue_page(MigrationState *ms, 
> ram_addr_t *offset,
>      return block;
>  }
>  
> -/*
> - * Unqueue a page from the queue fed by postcopy page requests; skips pages
> - * that are already sent (!dirty)
> +/**
> + * get_queued_page: unqueue a page from the postocpy requests
>   *
> - *      ms:      MigrationState in
> - *     pss:      PageSearchStatus structure updated with found block/offset
> - * ram_addr_abs: global offset in the dirty/sent bitmaps
> + * Skips pages that are already sent (!dirty)
>   *
> - * Returns:      true if a queued page is found
> + * Returns if a queued page is found
> + *
> + * @ms: current migration state
> + * @pss: data about the state of the current dirty page scan
> + * @ram_addr_abs: pointer into which to store the address of the dirty page
> + *                within the global ram_addr space
>   */
>  static bool get_queued_page(MigrationState *ms, PageSearchStatus *pss,
>                              ram_addr_t *ram_addr_abs)
> @@ -1157,11 +1186,12 @@ static bool get_queued_page(MigrationState *ms, 
> PageSearchStatus *pss,
>  }
>  
>  /**
> - * flush_page_queue: Flush any remaining pages in the ram request queue
> - *    it should be empty at the end anyway, but in error cases there may be
> - *    some left.
> + * flush_page_queue: flush any remaining pages in the ram request queue
>   *
> - * ms: MigrationState
> + * It should be empty at the end anyway, but in error cases there may
> + * xbe some left.
> + *
> + * @ms: current migration state
>   */
>  void flush_page_queue(MigrationState *ms)
>  {
> @@ -1179,12 +1209,17 @@ void flush_page_queue(MigrationState *ms)
>  }
>  
>  /**
> - * Queue the pages for transmission, e.g. a request from postcopy destination
> - *   ms: MigrationStatus in which the queue is held
> - *   rbname: The RAMBlock the request is for - may be NULL (to mean reuse 
> last)
> - *   start: Offset from the start of the RAMBlock
> - *   len: Length (in bytes) to send
> - *   Return: 0 on success
> + * ram_save_queue_pages: queue the page for transmission
> + *
> + * A request from postcopy destination for example.
> + *
> + * Returns zero on success or negative on error
> + *
> + * @ms: current migration state
> + * @rbname: Name of the RAMBLock of the request. NULL means the
> + *          same that last one.
> + * @start: starting address from the start of the RAMBlock
> + * @len: length (in bytes) to send
>   */
>  int ram_save_queue_pages(MigrationState *ms, const char *rbname,
>                           ram_addr_t start, ram_addr_t len)
> @@ -1243,17 +1278,16 @@ err:
>  }
>  
>  /**
> - * ram_save_target_page: Save one target page
> + * ram_save_target_page: save one target page
>   *
> + * Returns the umber of pages written

Missing ''n'

>   *
> + * @ms: current migration state
>   * @f: QEMUFile where to send the data
> - * @block: pointer to block that contains the page we want to send
> - * @offset: offset inside the block for the page;
> + * @pss: data about the page we want to send
>   * @last_stage: if we are at the completion stage
>   * @bytes_transferred: increase it with the number of transferred bytes
> - * @dirty_ram_abs: Address of the start of the dirty page in ram_addr_t space
> - *
> - * Returns: Number of pages written.
> + * @dirty_ram_abs: address of the start of the dirty page in ram_addr_t space
>   */
>  static int ram_save_target_page(MigrationState *ms, QEMUFile *f,
>                                  PageSearchStatus *pss,
> @@ -1295,20 +1329,19 @@ static int ram_save_target_page(MigrationState *ms, 
> QEMUFile *f,
>  }
>  
>  /**
> - * ram_save_host_page: Starting at *offset send pages up to the end
> - *                     of the current host page.  It's valid for the initial
> - *                     offset to point into the middle of a host page
> - *                     in which case the remainder of the hostpage is sent.
> - *                     Only dirty target pages are sent.
> - *                     Note that the host page size may be a huge page for 
> this
> - *                     block.
> + * ram_save_host_page: save a whole host page
>   *
> - * Returns: Number of pages written.
> + * Starting at *offset send pages up to the end of the current host
> + * page. It's valid for the initial offset to point into the middle of
> + * a host page in which case the remainder of the hostpage is sent.
> + * Only dirty target pages are sent. Note that the host page size may
> + * be a huge page for this block.
>   *
> + * Returns the number of pages written or negative on error
> + *
> + * @ms: current migration state
>   * @f: QEMUFile where to send the data
> - * @block: pointer to block that contains the page we want to send
> - * @offset: offset inside the block for the page; updated to last target page
> - *          sent
> + * @pss: data about the page we want to send
>   * @last_stage: if we are at the completion stage
>   * @bytes_transferred: increase it with the number of transferred bytes
>   * @dirty_ram_abs: Address of the start of the dirty page in ram_addr_t space
> @@ -1340,12 +1373,11 @@ static int ram_save_host_page(MigrationState *ms, 
> QEMUFile *f,
>  }
>  
>  /**
> - * ram_find_and_save_block: Finds a dirty page and sends it to f
> + * ram_find_and_save_block: finds a dirty page and sends it to f
>   *
>   * Called within an RCU critical section.
>   *
> - * Returns:  The number of pages written
> - *           0 means no dirty pages
> + * Returns the number of pages written where zero means no dirty pages
>   *
>   * @f: QEMUFile where to send the data
>   * @last_stage: if we are at the completion stage
> @@ -1580,12 +1612,19 @@ void 
> ram_postcopy_migrated_memory_release(MigrationState *ms)
>      }
>  }
>  
> -/*
> +/**
> + * postcopy_send_discard_bm_ram: discard a RAMBlock
> + *
> + * Returns zero on success
> + *
>   * Callback from postcopy_each_ram_send_discard for each RAMBlock
>   * Note: At this point the 'unsentmap' is the processed bitmap combined
>   *       with the dirtymap; so a '1' means it's either dirty or unsent.
> - * start,length: Indexes into the bitmap for the first bit
> - *            representing the named block and length in target-pages
> + *
> + * @ms: current migration state
> + * @pds: state for postcopy
> + * @start: RAMBlock starting page
> + * @length: RAMBlock size
>   */
>  static int postcopy_send_discard_bm_ram(MigrationState *ms,
>                                          PostcopyDiscardState *pds,
> @@ -1621,13 +1660,18 @@ static int 
> postcopy_send_discard_bm_ram(MigrationState *ms,
>      return 0;
>  }
>  
> -/*
> +/**
> + * postcopy_each_ram_send_discard: discard all RAMBlocks
> + *
> + * Returns 0 for success or negative for error
> + *
>   * Utility for the outgoing postcopy code.
>   *   Calls postcopy_send_discard_bm_ram for each RAMBlock
>   *   passing it bitmap indexes and name.
> - * Returns: 0 on success
>   * (qemu_ram_foreach_block ends up passing unscaled lengths
>   *  which would mean postcopy code would have to deal with target page)
> + *
> + * @ms: current migration state
>   */
>  static int postcopy_each_ram_send_discard(MigrationState *ms)
>  {
> @@ -1656,17 +1700,21 @@ static int 
> postcopy_each_ram_send_discard(MigrationState *ms)
>      return 0;
>  }
>  
> -/*
> - * Helper for postcopy_chunk_hostpages; it's called twice to cleanup
> - *   the two bitmaps, that are similar, but one is inverted.
> +/**
> + * postcopy_chuck_hostpages_pass: canocalize bitmap in hostpages
>   *
> - * We search for runs of target-pages that don't start or end on a
> - * host page boundary;
> - * unsent_pass=true: Cleans up partially unsent host pages by searching
> - *                 the unsentmap
> - * unsent_pass=false: Cleans up partially dirty host pages by searching
> - *                 the main migration bitmap
> + * Helper for postcopy_chunk_hostpages; it's called twice to
> + * canonicalize the two bitmaps, that are similar, but one is
> + * inverted.
>   *
> + * Postcopy requires that all target pages in a hostpage are dirty or
> + * clean, not a mix.  This function canonicalizes the bitmaps.
> + *
> + * @ms: current migration state
> + * @unsent_pass: if true we need to canonicalize partially unsent host pages
> + *               otherwise we need to canonicalize partially dirty host pages
> + * @block: block that contains the page we want to canonicalize
> + * @pds: state for postcopy
>   */
>  static void postcopy_chunk_hostpages_pass(MigrationState *ms, bool 
> unsent_pass,
>                                            RAMBlock *block,
> @@ -1784,14 +1832,18 @@ static void 
> postcopy_chunk_hostpages_pass(MigrationState *ms, bool unsent_pass,
>      }
>  }
>  
> -/*
> +/**
> + * postcopy_chuck_hostpages: discrad any partially sent host page
> + *
>   * Utility for the outgoing postcopy code.
>   *
>   * Discard any partially sent host-page size chunks, mark any partially
>   * dirty host-page size chunks as all dirty.  In this case the host-page
>   * is the host-page for the particular RAMBlock, i.e. it might be a huge page
>   *
> - * Returns: 0 on success
> + * Returns zero on success
> + *
> + * @ms: current migration state
>   */
>  static int postcopy_chunk_hostpages(MigrationState *ms)
>  {
> @@ -1822,7 +1874,11 @@ static int postcopy_chunk_hostpages(MigrationState *ms)
>      return 0;
>  }
>  
> -/*
> +/**
> + * ram_postcopy_send_discard_bitmap: transmit the discard bitmap
> + *
> + * Returns zero on success
> + *
>   * Transmit the set of pages to be discarded after precopy to the target
>   * these are pages that:
>   *     a) Have been previously transmitted but are now dirty again
> @@ -1830,6 +1886,8 @@ static int postcopy_chunk_hostpages(MigrationState *ms)
>   *        any pages on the destination that have been mapped by background
>   *        tasks get discarded (transparent huge pages is the specific 
> concern)
>   * Hopefully this is pretty sparse
> + *
> + * @ms: current migration state
>   */
>  int ram_postcopy_send_discard_bitmap(MigrationState *ms)
>  {
> @@ -1878,13 +1936,16 @@ int ram_postcopy_send_discard_bitmap(MigrationState 
> *ms)
>      return ret;
>  }
>  
> -/*
> - * At the start of the postcopy phase of migration, any now-dirty
> - * precopied pages are discarded.
> +/**
> + * ram_discard_range: discard dirtied pages at the beginning of postcopy
>   *
> - * start, length describe a byte address range within the RAMBlock
> + * Returns zero on success
>   *
> - * Returns 0 on success.
> + * @mis: current migration incoming state
> + * @block_name: Name of the RAMBLock of the request. NULL means the
 'BL'->'Bl'

> + *              same that last one.
> + * @start: RAMBlock starting page
> + * @length: RAMBlock size
>   */
>  int ram_discard_range(MigrationIncomingState *mis,
>                        const char *block_name,
> @@ -1987,12 +2048,21 @@ static int ram_save_init_globals(void)
>      return 0;
>  }
>  
> -/* Each of ram_save_setup, ram_save_iterate and ram_save_complete has
> +/*
> + * Each of ram_save_setup, ram_save_iterate and ram_save_complete has
>   * long-running RCU critical section.  When rcu-reclaims in the code
>   * start to become numerous it will be necessary to reduce the
>   * granularity of these critical sections.
>   */
>  
> +/**
> + * ram_save_setup: Setup RAM for migration
> + *
> + * Returns zero to indicate success and negative for error
> + *
> + * @f: QEMUFile where to send the data
> + * @opaque: RAMState pointer
> + */
>  static int ram_save_setup(QEMUFile *f, void *opaque)
>  {
>      RAMBlock *block;
> @@ -2027,6 +2097,14 @@ static int ram_save_setup(QEMUFile *f, void *opaque)
>      return 0;
>  }
>  
> +/**
> + * ram_save_setup: iterative stage for migration
> + *
> + * Returns zero to indicate success and negative for error
> + *
> + * @f: QEMUFile where to send the data
> + * @opaque: RAMState pointer
> + */
>  static int ram_save_iterate(QEMUFile *f, void *opaque)
>  {
>      int ret;
> @@ -2091,7 +2169,16 @@ static int ram_save_iterate(QEMUFile *f, void *opaque)
>      return done;
>  }
>  
> -/* Called with iothread lock */
> +/**
> + * ram_save_complete: function called to send the remaining amount of ram
> + *
> + * Returns zero to indicate success
> + *
> + * Called with iothread lock
> + *
> + * @f: QEMUFile where to send the data
> + * @opaque: RAMState pointer
> + */
>  static int ram_save_complete(QEMUFile *f, void *opaque)
>  {
>      rcu_read_lock();
> @@ -2185,17 +2272,17 @@ static int load_xbzrle(QEMUFile *f, ram_addr_t addr, 
> void *host)
>      return 0;
>  }
>  
> -/* Must be called from within a rcu critical section.
> +/**
> + * ram_block_from_stream: read a RAMBlock id from the migration stream
> + *
> + * Must be called from within a rcu critical section.
> + *
>   * Returns a pointer from within the RCU-protected ram_list.
> - */
> -/*
> - * Read a RAMBlock ID from the stream f.
>   *
> - * f: Stream to read from
> - * flags: Page flags (mostly to see if it's a continuation of previous block)
> + * @f: QEMUFile where to read the data from
> + * @flags: Page flags (mostly to see if it's a continuation of previous 
> block)
>   */
> -static inline RAMBlock *ram_block_from_stream(QEMUFile *f,
> -                                              int flags)
> +static inline RAMBlock *ram_block_from_stream(QEMUFile *f, int flags)
>  {
>      static RAMBlock *block = NULL;
>      char id[256];
> @@ -2232,9 +2319,15 @@ static inline void 
> *host_from_ram_block_offset(RAMBlock *block,
>      return block->host + offset;
>  }
>  
> -/*
> +/**
> + * ram_handle_compressed: handle the zero page case
> + *
>   * If a page (or a whole RDMA chunk) has been
>   * determined to be zero, then zap it.
> + *
> + * @host: host address for the zero page
> + * @ch: what the page is filled from.  We only support zero
> + * @size: size of the zero page
>   */
>  void ram_handle_compressed(void *host, uint8_t ch, uint64_t size)
>  {
> @@ -2373,9 +2466,16 @@ static void 
> decompress_data_with_multi_threads(QEMUFile *f,
>      qemu_mutex_unlock(&decomp_done_lock);
>  }
>  
> -/*
> - * Allocate data structures etc needed by incoming migration with 
> postcopy-ram
> - * postcopy-ram's similarly names postcopy_ram_incoming_init does the work
> +/**
> + * ram_postococpy_incoming_init: allocate postcopy data structures
          ^^^^^^^^^^
 typo

> + *
> + * Returns 0 for success and negative if there was one error
> + *
> + * @mis: current migration incoming state
> + *
> + * Allocate data structures etc needed by incoming migration with
> + * postcopy-ram postcopy-ram's similarly names
> + * postcopy_ram_incoming_init does the work
>   */
>  int ram_postcopy_incoming_init(MigrationIncomingState *mis)
>  {
> @@ -2384,9 +2484,15 @@ int ram_postcopy_incoming_init(MigrationIncomingState 
> *mis)
>      return postcopy_ram_incoming_init(mis, ram_pages);
>  }
>  
> -/*
> +/**
> + * ram_load_postocpy: load a page in postcopy case
               ^^^^^^^^

typo

Dave

> + *
> + * Returns 0 for success or -errno in case of error
> + *
>   * Called in postcopy mode by ram_load().
>   * rcu_read_lock is taken prior to this being called.
> + *
> + * @f: QEMUFile where to send the data
>   */
>  static int ram_load_postcopy(QEMUFile *f)
>  {
> -- 
> 2.9.3
> 
--
Dr. David Alan Gilbert / address@hidden / Manchester, UK