slirp/src/vmstate.h

   1 /*
   2  * QEMU migration/snapshot declarations
   3  *
   4  * Copyright (c) 2009-2011 Red Hat, Inc.
   5  *
   6  * Original author: Juan Quintela <quintela@redhat.com>
   7  *
   8  * Permission is hereby granted, free of charge, to any person obtaining a copy
   9  * of this software and associated documentation files (the "Software"), to deal
  10  * in the Software without restriction, including without limitation the rights
  11  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  12  * copies of the Software, and to permit persons to whom the Software is
  13  * furnished to do so, subject to the following conditions:
  14  *
  15  * The above copyright notice and this permission notice shall be included in
  16  * all copies or substantial portions of the Software.
  17  *
  18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  19  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  21  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  22  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  23  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  24  * THE SOFTWARE.
  25  */
  26 #ifndef VMSTATE_H_
  27 #define VMSTATE_H_
  28
  29 #include <unistd.h>
  30 #include <stdint.h>
  31 #include <stdbool.h>
  32 #include "slirp.h"
  33 #include "stream.h"
  34
  35 #define stringify(s) tostring(s)
  36 #define tostring(s) #s
  37
  38 typedef struct VMStateInfo VMStateInfo;
  39 typedef struct VMStateDescription VMStateDescription;
  40 typedef struct VMStateField VMStateField;
  41
  42 int slirp_vmstate_save_state(SlirpOStream *f, const VMStateDescription *vmsd,
  43                              void *opaque);
  44 int slirp_vmstate_load_state(SlirpIStream *f, const VMStateDescription *vmsd,
  45                              void *opaque, int version_id);
  46
  47 /* VMStateInfo allows customized migration of objects that don't fit in
  48  * any category in VMStateFlags. Additional information is always passed
  49  * into get and put in terms of field and vmdesc parameters. However
  50  * these two parameters should only be used in cases when customized
  51  * handling is needed, such as QTAILQ. For primitive data types such as
  52  * integer, field and vmdesc parameters should be ignored inside get/put.
  53  */
  54 struct VMStateInfo {
  55     const char *name;
  56     int (*get)(SlirpIStream *f, void *pv, size_t size, const VMStateField *field);
  57     int (*put)(SlirpOStream *f, void *pv, size_t size, const VMStateField *field);
  58 };
  59
  60 enum VMStateFlags {
  61     /* Ignored */
  62     VMS_SINGLE           = 0x001,
  63
  64     /* The struct member at opaque + VMStateField.offset is a pointer
  65      * to the actual field (e.g. struct a { uint8_t *b;
  66      * }). Dereference the pointer before using it as basis for
  67      * further pointer arithmetic (see e.g. VMS_ARRAY). Does not
  68      * affect the meaning of VMStateField.num_offset or
  69      * VMStateField.size_offset; see VMS_VARRAY* and VMS_VBUFFER for
  70      * those. */
  71     VMS_POINTER          = 0x002,
  72
  73     /* The field is an array of fixed size. VMStateField.num contains
  74      * the number of entries in the array. The size of each entry is
  75      * given by VMStateField.size and / or opaque +
  76      * VMStateField.size_offset; see VMS_VBUFFER and
  77      * VMS_MULTIPLY. Each array entry will be processed individually
  78      * (VMStateField.info.get()/put() if VMS_STRUCT is not set,
  79      * recursion into VMStateField.vmsd if VMS_STRUCT is set). May not
  80      * be combined with VMS_VARRAY*. */
  81     VMS_ARRAY            = 0x004,
  82
  83     /* The field is itself a struct, containing one or more
  84      * fields. Recurse into VMStateField.vmsd. Most useful in
  85      * combination with VMS_ARRAY / VMS_VARRAY*, recursing into each
  86      * array entry. */
  87     VMS_STRUCT           = 0x008,
  88
  89     /* The field is an array of variable size. The int32_t at opaque +
  90      * VMStateField.num_offset contains the number of entries in the
  91      * array. See the VMS_ARRAY description regarding array handling
  92      * in general. May not be combined with VMS_ARRAY or any other
  93      * VMS_VARRAY*. */
  94     VMS_VARRAY_INT32     = 0x010,
  95
  96     /* Ignored */
  97     VMS_BUFFER           = 0x020,
  98
  99     /* The field is a (fixed-size or variable-size) array of pointers
 100      * (e.g. struct a { uint8_t *b[]; }). Dereference each array entry
 101      * before using it. Note: Does not imply any one of VMS_ARRAY /
 102      * VMS_VARRAY*; these need to be set explicitly. */
 103     VMS_ARRAY_OF_POINTER = 0x040,
 104
 105     /* The field is an array of variable size. The uint16_t at opaque
 106      * + VMStateField.num_offset (subject to VMS_MULTIPLY_ELEMENTS)
 107      * contains the number of entries in the array. See the VMS_ARRAY
 108      * description regarding array handling in general. May not be
 109      * combined with VMS_ARRAY or any other VMS_VARRAY*. */
 110     VMS_VARRAY_UINT16    = 0x080,
 111
 112     /* The size of the individual entries (a single array entry if
 113      * VMS_ARRAY or any of VMS_VARRAY* are set, or the field itself if
 114      * neither is set) is variable (i.e. not known at compile-time),
 115      * but the same for all entries. Use the int32_t at opaque +
 116      * VMStateField.size_offset (subject to VMS_MULTIPLY) to determine
 117      * the size of each (and every) entry. */
 118     VMS_VBUFFER          = 0x100,
 119
 120     /* Multiply the entry size given by the int32_t at opaque +
 121      * VMStateField.size_offset (see VMS_VBUFFER description) with
 122      * VMStateField.size to determine the number of bytes to be
 123      * allocated. Only valid in combination with VMS_VBUFFER. */
 124     VMS_MULTIPLY         = 0x200,
 125
 126     /* The field is an array of variable size. The uint8_t at opaque +
 127      * VMStateField.num_offset (subject to VMS_MULTIPLY_ELEMENTS)
 128      * contains the number of entries in the array. See the VMS_ARRAY
 129      * description regarding array handling in general. May not be
 130      * combined with VMS_ARRAY or any other VMS_VARRAY*. */
 131     VMS_VARRAY_UINT8     = 0x400,
 132
 133     /* The field is an array of variable size. The uint32_t at opaque
 134      * + VMStateField.num_offset (subject to VMS_MULTIPLY_ELEMENTS)
 135      * contains the number of entries in the array. See the VMS_ARRAY
 136      * description regarding array handling in general. May not be
 137      * combined with VMS_ARRAY or any other VMS_VARRAY*. */
 138     VMS_VARRAY_UINT32    = 0x800,
 139
 140     /* Fail loading the serialised VM state if this field is missing
 141      * from the input. */
 142     VMS_MUST_EXIST       = 0x1000,
 143
 144     /* When loading serialised VM state, allocate memory for the
 145      * (entire) field. Only valid in combination with
 146      * VMS_POINTER. Note: Not all combinations with other flags are
 147      * currently supported, e.g. VMS_ALLOC|VMS_ARRAY_OF_POINTER won't
 148      * cause the individual entries to be allocated. */
 149     VMS_ALLOC            = 0x2000,
 150
 151     /* Multiply the number of entries given by the integer at opaque +
 152      * VMStateField.num_offset (see VMS_VARRAY*) with VMStateField.num
 153      * to determine the number of entries in the array. Only valid in
 154      * combination with one of VMS_VARRAY*. */
 155     VMS_MULTIPLY_ELEMENTS = 0x4000,
 156
 157     /* A structure field that is like VMS_STRUCT, but uses
 158      * VMStateField.struct_version_id to tell which version of the
 159      * structure we are referencing to use. */
 160     VMS_VSTRUCT           = 0x8000,
 161 };
 162
 163 struct VMStateField {
 164     const char *name;
 165     size_t offset;
 166     size_t size;
 167     size_t start;
 168     int num;
 169     size_t num_offset;
 170     size_t size_offset;
 171     const VMStateInfo *info;
 172     enum VMStateFlags flags;
 173     const VMStateDescription *vmsd;
 174     int version_id;
 175     int struct_version_id;
 176     bool (*field_exists)(void *opaque, int version_id);
 177 };
 178
 179 struct VMStateDescription {
 180     const char *name;
 181     int version_id;
 182     int (*pre_load)(void *opaque);
 183     int (*post_load)(void *opaque, int version_id);
 184     int (*pre_save)(void *opaque);
 185     VMStateField *fields;
 186 };
 187
 188
 189 extern const VMStateInfo slirp_vmstate_info_int16;
 190 extern const VMStateInfo slirp_vmstate_info_int32;
 191 extern const VMStateInfo slirp_vmstate_info_uint8;
 192 extern const VMStateInfo slirp_vmstate_info_uint16;
 193 extern const VMStateInfo slirp_vmstate_info_uint32;
 194
 195 /** Put this in the stream when migrating a null pointer.*/
 196 #define VMS_NULLPTR_MARKER (0x30U) /* '0' */
 197 extern const VMStateInfo slirp_vmstate_info_nullptr;
 198
 199 extern const VMStateInfo slirp_vmstate_info_buffer;
 200 extern const VMStateInfo slirp_vmstate_info_tmp;
 201
 202 #define type_check_array(t1,t2,n) ((t1(*)[n])0 - (t2*)0)
 203 #define type_check_pointer(t1,t2) ((t1**)0 - (t2*)0)
 204 #define typeof_field(type, field) typeof(((type *)0)->field)
 205 #define type_check(t1,t2) ((t1*)0 - (t2*)0)
 206
 207 #define vmstate_offset_value(_state, _field, _type)                  \
 208     (offsetof(_state, _field) +                                      \
 209      type_check(_type, typeof_field(_state, _field)))
 210
 211 #define vmstate_offset_pointer(_state, _field, _type)                \
 212     (offsetof(_state, _field) +                                      \
 213      type_check_pointer(_type, typeof_field(_state, _field)))
 214
 215 #define vmstate_offset_array(_state, _field, _type, _num)            \
 216     (offsetof(_state, _field) +                                      \
 217      type_check_array(_type, typeof_field(_state, _field), _num))
 218
 219 #define vmstate_offset_buffer(_state, _field)                        \
 220     vmstate_offset_array(_state, _field, uint8_t,                    \
 221                          sizeof(typeof_field(_state, _field)))
 222
 223 /* In the macros below, if there is a _version, that means the macro's
 224  * field will be processed only if the version being received is >=
 225  * the _version specified.  In general, if you add a new field, you
 226  * would increment the structure's version and put that version
 227  * number into the new field so it would only be processed with the
 228  * new version.
 229  *
 230  * In particular, for VMSTATE_STRUCT() and friends the _version does
 231  * *NOT* pick the version of the sub-structure.  It works just as
 232  * specified above.  The version of the top-level structure received
 233  * is passed down to all sub-structures.  This means that the
 234  * sub-structures must have version that are compatible with all the
 235  * structures that use them.
 236  *
 237  * If you want to specify the version of the sub-structure, use
 238  * VMSTATE_VSTRUCT(), which allows the specific sub-structure version
 239  * to be directly specified.
 240  */
 241
 242 #define VMSTATE_SINGLE_TEST(_field, _state, _test, _version, _info, _type) { \
 243     .name         = (stringify(_field)),                             \
 244     .version_id   = (_version),                                      \
 245     .field_exists = (_test),                                         \
 246     .size         = sizeof(_type),                                   \
 247     .info         = &(_info),                                        \
 248     .flags        = VMS_SINGLE,                                      \
 249     .offset       = vmstate_offset_value(_state, _field, _type),     \
 250 }
 251
 252 #define VMSTATE_ARRAY(_field, _state, _num, _version, _info, _type) {\
 253     .name       = (stringify(_field)),                               \
 254     .version_id = (_version),                                        \
 255     .num        = (_num),                                            \
 256     .info       = &(_info),                                          \
 257     .size       = sizeof(_type),                                     \
 258     .flags      = VMS_ARRAY,                                         \
 259     .offset     = vmstate_offset_array(_state, _field, _type, _num), \
 260 }
 261
 262 #define VMSTATE_STRUCT_TEST(_field, _state, _test, _version, _vmsd, _type) { \
 263     .name         = (stringify(_field)),                             \
 264     .version_id   = (_version),                                      \
 265     .field_exists = (_test),                                         \
 266     .vmsd         = &(_vmsd),                                        \
 267     .size         = sizeof(_type),                                   \
 268     .flags        = VMS_STRUCT,                                      \
 269     .offset       = vmstate_offset_value(_state, _field, _type),     \
 270 }
 271
 272 #define VMSTATE_STRUCT_POINTER_V(_field, _state, _version, _vmsd, _type) { \
 273     .name         = (stringify(_field)),                             \
 274     .version_id   = (_version),                                        \
 275     .vmsd         = &(_vmsd),                                        \
 276     .size         = sizeof(_type *),                                 \
 277     .flags        = VMS_STRUCT|VMS_POINTER,                          \
 278     .offset       = vmstate_offset_pointer(_state, _field, _type),   \
 279 }
 280
 281 #define VMSTATE_STRUCT_ARRAY_TEST(_field, _state, _num, _test, _version, _vmsd, _type) { \
 282     .name         = (stringify(_field)),                             \
 283     .num          = (_num),                                          \
 284     .field_exists = (_test),                                         \
 285     .version_id   = (_version),                                      \
 286     .vmsd         = &(_vmsd),                                        \
 287     .size         = sizeof(_type),                                   \
 288     .flags        = VMS_STRUCT|VMS_ARRAY,                            \
 289     .offset       = vmstate_offset_array(_state, _field, _type, _num),\
 290 }
 291
 292 #define VMSTATE_STATIC_BUFFER(_field, _state, _version, _test, _start, _size) { \
 293     .name         = (stringify(_field)),                             \
 294     .version_id   = (_version),                                      \
 295     .field_exists = (_test),                                         \
 296     .size         = (_size - _start),                                \
 297     .info         = &slirp_vmstate_info_buffer,                      \
 298     .flags        = VMS_BUFFER,                                      \
 299     .offset       = vmstate_offset_buffer(_state, _field) + _start,  \
 300 }
 301
 302 #define VMSTATE_VBUFFER_UINT32(_field, _state, _version, _test, _field_size) { \
 303     .name         = (stringify(_field)),                             \
 304     .version_id   = (_version),                                      \
 305     .field_exists = (_test),                                         \
 306     .size_offset  = vmstate_offset_value(_state, _field_size, uint32_t),\
 307     .info         = &slirp_vmstate_info_buffer,                      \
 308     .flags        = VMS_VBUFFER|VMS_POINTER,                         \
 309     .offset       = offsetof(_state, _field),                        \
 310 }
 311
 312 #define QEMU_BUILD_BUG_ON_STRUCT(x)             \
 313     struct {                                    \
 314         int:(x) ? -1 : 1;                       \
 315     }
 316
 317 #define QEMU_BUILD_BUG_ON_ZERO(x) (sizeof(QEMU_BUILD_BUG_ON_STRUCT(x)) - \
 318                                    sizeof(QEMU_BUILD_BUG_ON_STRUCT(x)))
 319
 320 /* Allocate a temporary of type 'tmp_type', set tmp->parent to _state
 321  * and execute the vmsd on the temporary.  Note that we're working with
 322  * the whole of _state here, not a field within it.
 323  * We compile time check that:
 324  *    That _tmp_type contains a 'parent' member that's a pointer to the
 325  *        '_state' type
 326  *    That the pointer is right at the start of _tmp_type.
 327  */
 328 #define VMSTATE_WITH_TMP(_state, _tmp_type, _vmsd) {                 \
 329     .name         = "tmp",                                           \
 330     .size         = sizeof(_tmp_type) +                              \
 331                     QEMU_BUILD_BUG_ON_ZERO(offsetof(_tmp_type, parent) != 0) + \
 332                     type_check_pointer(_state,                       \
 333                         typeof_field(_tmp_type, parent)),            \
 334     .vmsd         = &(_vmsd),                                        \
 335     .info         = &slirp_vmstate_info_tmp,                         \
 336 }
 337
 338 #define VMSTATE_SINGLE(_field, _state, _version, _info, _type)          \
 339     VMSTATE_SINGLE_TEST(_field, _state, NULL, _version, _info, _type)
 340
 341 #define VMSTATE_STRUCT(_field, _state, _version, _vmsd, _type)        \
 342     VMSTATE_STRUCT_TEST(_field, _state, NULL, _version, _vmsd, _type)
 343
 344 #define VMSTATE_STRUCT_POINTER(_field, _state, _vmsd, _type)          \
 345     VMSTATE_STRUCT_POINTER_V(_field, _state, 0, _vmsd, _type)
 346
 347 #define VMSTATE_STRUCT_ARRAY(_field, _state, _num, _version, _vmsd, _type) \
 348     VMSTATE_STRUCT_ARRAY_TEST(_field, _state, _num, NULL, _version,   \
 349             _vmsd, _type)
 350
 351 #define VMSTATE_INT16_V(_f, _s, _v)                                   \
 352     VMSTATE_SINGLE(_f, _s, _v, slirp_vmstate_info_int16, int16_t)
 353 #define VMSTATE_INT32_V(_f, _s, _v)                                   \
 354     VMSTATE_SINGLE(_f, _s, _v, slirp_vmstate_info_int32, int32_t)
 355
 356 #define VMSTATE_UINT8_V(_f, _s, _v)                                   \
 357     VMSTATE_SINGLE(_f, _s, _v, slirp_vmstate_info_uint8, uint8_t)
 358 #define VMSTATE_UINT16_V(_f, _s, _v)                                  \
 359     VMSTATE_SINGLE(_f, _s, _v, slirp_vmstate_info_uint16, uint16_t)
 360 #define VMSTATE_UINT32_V(_f, _s, _v)                                  \
 361     VMSTATE_SINGLE(_f, _s, _v, slirp_vmstate_info_uint32, uint32_t)
 362
 363 #define VMSTATE_INT16(_f, _s)                                         \
 364     VMSTATE_INT16_V(_f, _s, 0)
 365 #define VMSTATE_INT32(_f, _s)                                         \
 366     VMSTATE_INT32_V(_f, _s, 0)
 367
 368 #define VMSTATE_UINT8(_f, _s)                                         \
 369     VMSTATE_UINT8_V(_f, _s, 0)
 370 #define VMSTATE_UINT16(_f, _s)                                        \
 371     VMSTATE_UINT16_V(_f, _s, 0)
 372 #define VMSTATE_UINT32(_f, _s)                                        \
 373     VMSTATE_UINT32_V(_f, _s, 0)
 374
 375 #define VMSTATE_UINT16_TEST(_f, _s, _t)                               \
 376     VMSTATE_SINGLE_TEST(_f, _s, _t, 0, slirp_vmstate_info_uint16, uint16_t)
 377
 378 #define VMSTATE_UINT32_TEST(_f, _s, _t)                                  \
 379     VMSTATE_SINGLE_TEST(_f, _s, _t, 0, slirp_vmstate_info_uint32, uint32_t)
 380
 381 #define VMSTATE_INT16_ARRAY_V(_f, _s, _n, _v)                         \
 382     VMSTATE_ARRAY(_f, _s, _n, _v, slirp_vmstate_info_int16, int16_t)
 383
 384 #define VMSTATE_INT16_ARRAY(_f, _s, _n)                               \
 385     VMSTATE_INT16_ARRAY_V(_f, _s, _n, 0)
 386
 387 #define VMSTATE_BUFFER_V(_f, _s, _v)                                    \
 388     VMSTATE_STATIC_BUFFER(_f, _s, _v, NULL, 0, sizeof(typeof_field(_s, _f)))
 389
 390 #define VMSTATE_BUFFER(_f, _s)                                        \
 391     VMSTATE_BUFFER_V(_f, _s, 0)
 392
 393 #define VMSTATE_END_OF_LIST()                                         \
 394     {}
 395
 396 #endif