12.3 Data descriptions

The more complex task of the dumper is to be able to write lisp objects (lrecords) and C structs to disk and reload them at a different address, updating all the pointers they include in the process. This is done by using external data descriptions that give information about the layout of the structures in memory.

The specification of these descriptions is in lrecord.h. A description of an lrecord is an array of struct lrecord_description. Each of these structs include a type, an offset in the structure and some optional parameters depending on the type. For instance, here is the string description:

static const struct lrecord_description string_description[] = {
  { XD_BYTECOUNT,         offsetof (Lisp_String, size) },
  { XD_OPAQUE_DATA_PTR,   offsetof (Lisp_String, data), XD_INDIRECT(0, 1) },
  { XD_LISP_OBJECT,       offsetof (Lisp_String, plist) },
  { XD_END }
};

The first line indicates a member of type Bytecount, which is used by the next, indirect directive. The second means "there is a pointer to some opaque data in the field data". The length of said data is given by the expression XD_INDIRECT(0, 1), which means "the value in the 0th line of the description (welcome to C) plus one". The third line means "there is a Lisp_Object member plist in the Lisp_String structure". XD_END then ends the description.

This gives us all the information we need to move around what is pointed to by a structure (C or lrecord) and, by transitivity, everything that it points to. The only missing information for dumping is the size of the structure. For lrecords, this is part of the lrecord_implementation, so we don’t need to duplicate it. For C structures we use a struct struct_description, which includes a size field and a pointer to an associated array of lrecord_description.