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.

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.

Format

final

The format is divided into six parts:

  1. Magic: For identification purposes, DataComments MUST start with 0xDC.
  2. Tool ID: Every tool that parses and can export DataComments MUST register a 1-byte Tool ID for identification purposes and MUST default to identifying exported files with this byte.
  3. File Version: A user-provided ASCII string with the exported file's version information, end-padded with 0x00 to 9 bytes. Users SHOULD use a short SHA-1 from Git, if available, or a MAJOR.MINOR.PATCH version number, with two bytes each for MAJOR, MINOR, and PATCH. Applications MAY zero this field if no version information is available for the file.
  4. Export Date: Applications SHOULD 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). Applications with no access to the date MAY zero this field.
  5. Author Name: A length-prefixed ASCII string of up to 24 bytes containing identification information for the author. Applications MUST fail to parse this DataComment if the length is larger than 24 bytes. 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: 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