docs/virtio-migration.txt

   1 Virtio devices and migration
   2 ============================
   3
   4 Copyright 2015 IBM Corp.
   5
   6 This work is licensed under the terms of the GNU GPL, version 2 or later.  See
   7 the COPYING file in the top-level directory.
   8
   9 Saving and restoring the state of virtio devices is a bit of a twisty maze,
  10 for several reasons:
  11 - state is distributed between several parts:
  12   - virtio core, for common fields like features, number of queues, ...
  13   - virtio transport (pci, ccw, ...), for the different proxy devices and
  14     transport specific state (msix vectors, indicators, ...)
  15   - virtio device (net, blk, ...), for the different device types and their
  16     state (mac address, request queue, ...)
  17 - most fields are saved via the stream interface; subsequently, subsections
  18   have been added to make cross-version migration possible
  19
  20 This file attempts to document the current procedure and point out some
  21 caveats.
  22
  23
  24 Save state procedure
  25 ====================
  26
  27 virtio core               virtio transport          virtio device
  28 -----------               ----------------          -------------
  29
  30                                                     save() function registered
  31                                                     via register_savevm()
  32 virtio_save()                                       <----------
  33              ------>      save_config()
  34                           - save proxy device
  35                           - save transport-specific
  36                             device fields
  37 - save common device
  38   fields
  39 - save common virtqueue
  40   fields
  41              ------>      save_queue()
  42                           - save transport-specific
  43                             virtqueue fields
  44              ------>                               save_device()
  45                                                    - save device-specific
  46                                                      fields
  47 - save subsections
  48   - device endianness,
  49     if changed from
  50     default endianness
  51   - 64 bit features, if
  52     any high feature bit
  53     is set
  54   - virtio-1 virtqueue
  55     fields, if VERSION_1
  56     is set
  57
  58
  59 Load state procedure
  60 ====================
  61
  62 virtio core               virtio transport          virtio device
  63 -----------               ----------------          -------------
  64
  65                                                     load() function registered
  66                                                     via register_savevm()
  67 virtio_load()                                       <----------
  68              ------>      load_config()
  69                           - load proxy device
  70                           - load transport-specific
  71                             device fields
  72 - load common device
  73   fields
  74 - load common virtqueue
  75   fields
  76              ------>      load_queue()
  77                           - load transport-specific
  78                             virtqueue fields
  79 - notify guest
  80              ------>                               load_device()
  81                                                    - load device-specific
  82                                                      fields
  83 - load subsections
  84   - device endianness
  85   - 64 bit features
  86   - virtio-1 virtqueue
  87     fields
  88 - sanitize endianness
  89 - sanitize features
  90 - virtqueue index sanity
  91   check
  92                                                    - feature-dependent setup
  93
  94
  95 Implications of this setup
  96 ==========================
  97
  98 Devices need to be careful in their state processing during load: The
  99 load_device() procedure is invoked by the core before subsections have
 100 been loaded. Any code that depends on information transmitted in subsections
 101 therefore has to be invoked in the device's load() function _after_
 102 virtio_load() returned (like e.g. code depending on features).
 103
 104 Any extension of the state being migrated should be done in subsections
 105 added to the core for compatibility reasons. If transport or device specific
 106 state is added, core needs to invoke a callback from the new subsection.