From 34509387d2f80a3577d0b45eb6eceb09247dfc4a Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Wed, 21 Apr 2021 09:57:30 -0700 Subject: [PATCH 1/2] Starting to import background information into the documentation. A lot of this is based on the initial stuff documented in the Google Doc at https://interchange.vtr.tools Signed-off-by: Tim 'mithro' Ansell --- docs/common.md | 102 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 103 insertions(+) create mode 100644 docs/common.md diff --git a/docs/common.md b/docs/common.md new file mode 100644 index 0000000..3b2284f --- /dev/null +++ b/docs/common.md @@ -0,0 +1,102 @@ +# Common + +## Important Key Ideas + +### Versioning + + + +### Data, Representation and Encoding independence + +Everything in the interchange format should have a clear distinction between; + + * (a) the data "as a concept", + * (b) the data "as represented" and + * (c) the data "as encoded in a file format". + +For example, + + * (a) the data being represented could be "the name of an object", + * (b) but it could be represented as an integer pointing to a UTF-8 string + table, and + * (c) that could be encoded as either XML or Cap'n'Proto file format. + +### On disk representation + +The interchange format should define both; + + * (a) A compact binary machine readable format, **and** + * (b) a texted based human readable format. + +Tools should exist which do lossless conversion between the machine and human +readable formats. + +The preferred on disk formats for the interchange format are; + + * (a) Binary Machine readable format - **Cap'n'Proto** + * (b) Text based human readable format - **XML** + +These two formats where selected because, they have; + + * A well defined schema format. + * Good support by almost all languages, including the important languages of + C++, Python and Java. + * Already in use by core target tools. + +While **XML** is the preferred text based format, to enable wider adoption of +the interchange format, **optional** support for *alternative* human readable +text formats is encouraged. + +High value targets formats include; + + * JSON + * YAML + + +#### Schemas + +To make sure that files comply with the interchange specification, schemas for +the on-disk file formats which allow at least some automatic validation should +be provided. + +#### Backwards Compatibility + +Schema for the file formats should be extended to maintain backwards +compatibility will previous on-disk formats. + +Making breaking changes in on-disk formats require a new major version of the +specification to be published. + + +#### Common Metadata + +All files should have a set of common metadata to make it easy to connect files +together and understand their relationship. + +As the file output should be deterministic, files **should** include the +details required to reproduce the file output easily. + +This includes; + + * Checksum of inputs + * Information (version, command line arguments, random seed, etc) around + tooling used to create the file. + +Should **not** include; + + * Anything which makes builds not-reproducible. + See https://reproducible-builds.org/docs/ for common examples. + + +#### String Storage + + * A significant percentage of the data in all the files are strings that are + only needed for humans. + + * These strings are frequently used for identifiers. + + * For this reason special care has been taken around both the representation + and the on-disk encoding of these strings. + + + diff --git a/docs/index.rst b/docs/index.rst index d8dc21e..2b4efec 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,6 +5,7 @@ Welcome to FPGA Interchange documentation! :maxdepth: 2 :caption: Contents: + common device_resources bel_and_site_design pseudo_cells From 67917403c73b42cb27383567bb333dc8b113fac9 Mon Sep 17 00:00:00 2001 From: Tim Ansell Date: Wed, 21 Apr 2021 12:35:33 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Alessandro Comodi <44773360+acomodi@users.noreply.github.com> Co-authored-by: gatecat --- docs/common.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/common.md b/docs/common.md index 3b2284f..5547fd6 100644 --- a/docs/common.md +++ b/docs/common.md @@ -26,7 +26,7 @@ For example, The interchange format should define both; * (a) A compact binary machine readable format, **and** - * (b) a texted based human readable format. + * (b) a text based human readable format. Tools should exist which do lossless conversion between the machine and human readable formats. @@ -61,10 +61,10 @@ be provided. #### Backwards Compatibility -Schema for the file formats should be extended to maintain backwards -compatibility will previous on-disk formats. +Schemas for the file formats should be extended to maintain backwards +compatibility with previous on-disk formats. -Making breaking changes in on-disk formats require a new major version of the +Making breaking changes in on-disk formats requires a new major version of the specification to be published. @@ -99,4 +99,3 @@ Should **not** include; and the on-disk encoding of these strings. -