Custom Snapshots

While in most cases, snapshot-support is automatic for device model simply by registering the properties with the class. In some cases it may make sense to implement custom snapshots. To implement a custom snapshot a class must implement the ObjectIface (temu-c/Support/Objsys.h). This interface is optional but allows for custom serialisation routines to be implemented.

When saving a snapshot, the system first writes out all registered properties in an object (this process is known as serialisation). After the property serialisation, the optional serialise function in the (optional) ObjectIface is called.

When restoring a snapshot, the system first creates all objects by calling the constructors registered for a class, after this properties are restored, thirdly, if an object is of a class that implements the deserialise function that function is called.

When restoring a snapshot, the object constructors are called without arguments.

The snapshoting functions take two parameters, BaseName is the name of the file where the snapshot will be written, and Ctxt is a context pointer that can be used to insert and query additional property values in the snapshot file.

A typical use for the BaseName parameter is in the RAM and ROM models. These, by default, dump the raw data into binary files which will be named by adding a suffix to BaseName.

To serialize a special property in the custom snapshot interface, the following functions can be used:

// Write out a property
void temu_serialiseProp(void *Ctxt, const char *Name, temu_Type Typ,
                        int Count, void *Data);

// The following can be used to deserialise properties for objects.
// Get length of the property in the given context (i.e. number of
// elements)
int temu_snapshotGetLength(void *Ctxt, const char *Name);

// Get a value for the indexed property in the given context
temu_Propval temu_snapshotGetValue(void *Ctxt, const char *Name, int Idx);

To implement custom serialisation the ObjectIface is implemented. The following example shows how to match the serialise and deserialise functions for saving and restoring snapshots:

void
serialise(void *Obj, const char *BaseName, void *Ctxt)
{
  uint32_t Extra = 123;
  temu_serialiseProp(Ctxt, "myExtraProp", teTY_U32, 1, &Extra);
}

void
deserialise(void *Obj, const char *BaseName, void *Ctxt)
{
  assert(temu_snapshotGetLength(Ctxt, "myExtraProp") == 1);
  temu_Propval PV = temu_snapshotGetValue(Ctxt, "myExtraProp", 0);
}

temu_ObjectIface ObjIface = {
  serialise,
  deserialise,
  NULL, // checkSanity
};