Textual Configuration Format
============================

Project Trellis supports a simple text-based configuration format so that place-and-route, design manipulation and
design analysis tools do not have to deal with bitstream specifics, nor link directly to libtrellis.

Overview
---------
The text-based configuration format uses standard ASCII text files. ``#`` denotes a comment that continues until the
end of the line. ``.`` at the start of the line followed by the command type denotes a command. Command options follow
on the line, some commands may then have data on subsequent lines until the next command

Non-Tile Configuration
----------------------

``.device <device name>`` specifies the device type, for example ``.device LFE5U-85F``. This should always be the first
command in a file.

``.comment <comment>`` marks the rest of a line as a comment that is included in the header of the bitstream. The FPGA
ignores these, but they may be required if you wish to use vendor programming or deployment tools with the bitstream.

Tile Configuration
------------------

``.tile <tile name>`` denotes the start of a tile. Note that Project Trellis tile names are the Lattice tile name
followed by the colon and the tile type, for example ``MIB_R22C5:MIB_DSP1``. This is because the Lattice tile names
on their own are not unique.

Inside a tile there can be four entries: arcs, words, enums and unknown bits.

``arc: <sink> <source>`` enables an arc inside the tile, using the same Trellis relative netnames as used in the
database, for example ``arc: S3_V06S0303 E1_H01W0100``.

``word: <name> <value>`` sets the value of a configuration word (i.e. a configuration value that can reasonable be
split into bits, such as LUT initialisation). The value is always in binary, MSB first. For example
``word: SLICEC.K0.INIT 0101010101010101`` configures LUT0 in SLICEC to be an inverter.

``enum: <name> <value>`` sets the value of a configuration enum (i.e. a configuration value with multiple textual
values). In all cases one of the values from the Trellis database must be used. For example
``enum: PIOA.BASE_TYPE INPUT_LVCMOS25`` configures PIOA as a LVCMOS25 input.

``unknown: F<frame>B<bit>`` sets an unknown bit, specified by tile-relative frame and bit. For example
``unknown: F95B0`` sets unknown bit 0 in frame 95 in the tile.

Words and enums will not be included when converting a bitstream to textual configuration if they are at their default
value (i.e. the value they would have in a bitstream generated from an empty design).

Beware that some configuration words and enums are split across multiple tiles in features such as IO, EBR and DSPs.
To generate correct bitstreams, they must be included in every tile where they appear. Currently the value matcher, when
converting bitstreams to config looks at each tile individually, so may pick a config that is correct in each tile but
not overall. This will be fixed in the future.

Conversion
-----------

You can use ``libtrellis/examples/bit_to_config.py <bitstream>`` to convert a bitstream to a text config file, and
``libtrellis/examples/config_to_bit.py <config> <bitstream>`` to convert from config to a bitstream. C++ command line
tools and an install script are currently being developed.