On 5 March 2011 16:50, Peter Maydell <peter.mayd...@linaro.org> wrote: > I've appended a draft of a suggested extra section for > docs/migration.txt so you can tell me if I've misunderstood > it all :-)
Ping? In particular if somebody can fill in the [XXX] bit for me (and correct any other mistakes!) I'll submit this as a proper patch to the docs. > ---begin--- > === Adding state fields to a device === > > If you make a bugfix or enhancement to a device which requires the > addition of extra state, you need to add these new state fields > to the VMStateDescription so that: > (1) they are saved and loaded correctly > (2) migration between the new and old versions either works > or fails cleanly. > > If the change is such that migration between versions would not > work anyway, you can just add the new fields using the usual > VMSTATE_* macros, increment the version_id and set the > minimum_version_id to be the same as the version_id. > > Migration from the old version to the new version can be supported > if it is OK for the new fields to remain in their default state > [XXX is this right? are they zeroed, or do they get the value > the device's reset function sets them to, or something else?] > when the state of an old-version snapshot is loaded. To implement > this you need to use the VMSTATE_*_V macros which let you specify > the version in which a field was introduced, for instance: > > VMSTATE_UINT32_V(sys_cfgdata, arm_sysctl_state, 2) > > for a field introduced in version 2. You should also increment > the version_id, but leave the minimum_version_id unchanged. > Newly added VMSTATE_*_V fields should go at the end of the > VMState description. > > ---endit--- thanks -- PMM