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