docs/libtrellis/textconfig.rst - prjtrellis - Git at Google

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