slirp/src/vmstate.h

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