Skip to content

DataComment Specification

Jump to bottom
Ryan Pitasky edited this page Aug 21, 2024 · 5 revisions

TI's file format allows a comment with 42 bytes of arbitrary data. As of the writing of this specification, most tools simply overwrite the comment with information about the tool used to write the file. We propose a format that encodes more information into the same space, which should aid file identification.

Definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

An application or tool is DataComment-aware if it can export 8x files with the comment field set to a DataComment. DataComment-aware applications MUST default to exporting files with the comment set to a DataComment or a successor specification.

Format

final

The format is divided into six parts:

  1. Magic: For identification purposes, DataComments MUST start with 0xDC.
  2. Tool ID: Every DataComment-aware tool MUST register a 1-byte Tool ID for identification purposes and MUST default to identifying exported files with this byte.
  3. File Version: DataComments MUST include an ASCII string with the exported file's version information, end-padded with 0x00 to 9 bytes. This string MAY be either user-provided or generated from context (i.e. git commit hash, tag, or build number). DataComment-aware applications MAY zero this field if no version information is available for the file.
  4. Export Date: DataComment-aware applications MUST include the date of export in DDMMYYYY format, formatted as packed BCD (i.e., the high nibble is the tens digit, and the low nibble is the ones digit), or fill the field with 0x00 if they have no access to the date.
  5. Author Name: A length-prefixed ASCII string of up to 24 bytes containing identification information for the author. DataComment-aware applications MUST fail to parse this DataComment if the length is larger than 24 bytes. DataComment-aware applications MAY further restrict the length of this field to reserve bytes for application-specific data but MUST NOT fail to parse DataComments produced by other tools that do not further restrict the length.
  6. Extra Data: DataComment-aware applications MAY insert 24 - len(author_name) bytes of application-specific data after the author name. (how should this be preserved if another DataComment-aware application touches the file?)

Tool IDs in use:

...

Procedure for upgrading a file

(use the last printable, non-whitespace bytes of the existing comment as Extra Data because this often contains information about the tool)

Clone this wiki locally