# 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.