New data file format in version 6.0.0
In version 6.0.0 of hdl-registers (released 2024-08-25), the data file (TOML, JSON, etc) format is updated in a way that is not compatible with older files. This is done to enable the most requested feature in the history of the tool: The ability to group register fields arbitrarily, and not by field type. This is discussed in #116.
When the register parser in hdl-registers encounters an old data file, it will be automatically upgraded to the new format. The updated file will be saved next to the old file so that the user can inspect all changes that were made. Note that any comments or manual formatting in the original data file will be lost.
Example
Old format (left) vs new format (right) is shown below. You can right-click and open to view in full size.
Background
Before version 6.0.0 and since 2017, data was formatted e.g. like this:
register.register_name.mode
register.register_name.bit.field_name_1.descriptionregister.register_name.bit.field_name_1.default_valueregister.register_name.integer.field_name_2.descriptionregister.register_name.integer.field_name_2.default_valueregister.register_name.bit.field_name_3.descriptionregister.register_name.bit.field_name_3.default_value
In this representation, it was impossible to group fields in a manual order.
All bits would be bundled together, and all integers, etc.
In the example above, field_name_1 and field_name_3 would be placed together,
and field_name_2 would be placed after them.
As of version 6.0.0, the data is formatted like this:
register_name.mode
register_name.field_name_1.type = “bit”register_name.field_name_1.descriptionregister_name.field_name_1.default_valueregister_name.field_name_2.type = “integer”register_name.field_name_2.descriptionregister_name.field_name_2.default_valueregister_name.field_name_3.type = “bit”register_name.field_name_3.descriptionregister_name.field_name_3.default_value
With this format, fields are placed in exactly the same order as they appear in the data file. No matter their type. Same goes for registers and register arrays. Previously, all registers would always be placed before all register arrays, no matter the order they appeared in the data file. With this new data file format, registers and register arrays are placed in exactly the order they appear in the data file.
Specification and documentation
Example of data in the new file format can be found in all the examples on this website. For example here: TOML Format.
Format specifications are found in the corresponding articles in the menubar on the left. For example, if you are curious about how to specify a bit vector field, go to Bit vector fields.