CONFIGURATION_FILE

Overview

The primary purpose of the configuration file is to:

1) Parameterize the framework module's clock frequency, data widths, and signal polarities.
2) Provide a user-friendly way to specify I/0 pinout information for application modules.
3) Provide convenient mechanism to define some VHDL constants and aliases for framework signals.

If there is no config_file present in the source directory, SpeakHDL auto-generates a default configuration file named IO_CONFIG.cfg. When the ok command is given, SpeakHDL utilizes the IO_CONFIG.cfg file, multiple application module (.vhd) files and generates the top directory containing the top level, testbench, user definitions (.vhd) file, and pinout constraints (.xdc) file. When using a synthesis tool, all that is needed for input is the contents of the source folder and a reference a single library file placed in a location where it is accessible by all SpeakHDL projects.

The config file is divided into a single global section and multiple local sections. The global section parameters affect the entire HDL design and define values such as the system clock frequency, reset pin polarity and data-path bit widths. These values parameterize framework module, thus affect all application modules. ect. Local sections, on the other hand, define application module specific values. This is where module specific pin locations, VHDL aliases for I/O signals, and filenames for direct component instantiation can be specified. Each application module is required to have a corresponding local section entry which SpeakHDL keeps track of automatically.

It is fair to think of the config_file as the glue that pieces all the SpeakHDL files together and a mechanism that keeps the SpeakHDL files abstracted away from the specifics of any synthesis tool. As for syntax, the config_file accepts standard key-value pairs for most parameters. A single space is allowed in between the equal sign that separates pairs, and some values (such as pinout information) are allowed to specify using a comma separated list with our without leading and trailing brackets. In addition,
VHDL constants and aliases for framework signals are allowed to be declared inside the config file using standard VHDL syntax.

Example IO_CONFIG.cfg File

[global]
clk_pin = E3
reset_pin = U9
sys_clk_freq = 100E6
reset_polarity = '1'
data_width = 16
control_width = 16
default_shared_register_polarity = '0'
default_signal_polarity = '0'
default_voltage_standard = 3.3V
pinout_filename = PINOUT.xdc
command_help = False
voice_enabled = False
default_time_units = ms
alias srr is state_reg_rec(0);
alias state_reg : integer is state_reg_rec(0).state_reg;
[app_module_1]
input some_input_name(2) = H14, B9
output some_output_name(4) = A3, R5, Q1, J3
[app_module_2]
input addr_valid = V14
input bus_address(3) = reversed(X1, X2, X3)
input data_valid = U14
input data_write = V16
output data_wait = N9
io bus_data(8) = R14, R13, P13, T12, N11, R11, P10, R10

Syntax for Declaring I/O Signals

SpeakHDL uses the following syntax when declaring an I/O signal within the config file:

<mode> <name>[(<# pins>)] = <pinout location or comma separated list of locations>

The mode can be either input, output, or io, and the name is any valid VHDL identifier. When declaring an I/O signal to be of type std_logic, the number of pins is assumed to be (1) and is omitted. When declaring a std_logic_vector of length (2) or more, the size of the vector is specified in between parenthesis next to the signal name. In this way, one can readily see the width of any I/O and a vector valued signal will not be confused with a scalar valued signal. In addition, each I/O signal is required to have a unique pinout location assigned to it. std_logic signals must be assigned exactly one pin location while signals intended to be std_logic_vectors must have as many pin locations assigned as the width of the signal. These pin locations must be defined as a comma separated list. If the number of pin locations are not specified, or are inconsistent with the # pins, SpeakHDL calculates the # pins from the number of pin locations in the list when the 'ok' command is given.

For example, consider the following I/O declaration in a config file section where the # pins are not specified.

io bus_data = R14, R13, P13, T12, N11, R11, P10, R10

When the 'ok' command is given, SpeakHDL would update the I/O declaration with the calculated width of (8).

io bus_data(8) = R14, R13, P13, T12, N11, R11, P10, R10

Pinout List Ordering

Pinout locations for a vector valued signals are defined as a comma separated list of pinout locations. Due to the fact that a list is assumed to have indexes starting from 0 to N-1, pin location are also assumed to be assigned in ascending order from 0 to N-1. This sometimes leads to confusion when assigning pin locations for std_logic_vector which are assumed to have a downto range. As a convenience SpeakHDL allows pin location list to be reversed by using the reversed() syntax.

For example, the syntax below would reverse the pinout for an I/0 in the constraints file.

io bus_data(8) = reversed(R14, R13, P13, T12, N11, R11, P10, R10)

Global Section Parameters

Parameter Description type Allowable Values Default Values
clock_pin system clock pin location string <string> <>
reset_pin system reset pin location string <string> <>
sys_clk_freq default sys_clk frequency integer 1 - 400E6 100E6
reset_polarity system reset polarity std_logic {'0', '1'} '1'
data_width system data path width for fifo_data, shift_left,shift_right, exchange_register integer 0-64 32
control_width system control path width for shared_register integer 0-64 32
default_signal_polarity polarity when creating a new signal (default when-else logic) std_logic {'0', '1'} '0'
default_shared_register_polarity polarity of a shared_register when not asserted std_logic {'0', '1'} '0'
default_voltage_standard polarity generated in constraints file voltage {'2.5V', '3.0V', '3.3V'} 3.3V
pinout_filename name of auto-generated .xdc file string <name>.xdc PINOUT.xdc
default_time_units timing function units assumed when floating point value given in command string {us, ms, s} ms
command_help parameter specifying if help is printed on .vhd file boolean {True, False} True
voice_enabled parameter specifying if voice commands are enabled boolean {True, False} False

Command Reference

Voice and Hotkey Commands:

See also
Configuration File Commands

Notes and Warnings

Note
1) SpeakHDL updates the contents of the top directory each time the ok command is given.
2) The local section for an application module remains in the config file whether the module is enabled or disabled.
3) The config file reversed function only affects the pin locations in the constraints file, thus and only applies to synthesis. Whereas the use of the VHDL reversed function would affect both the simulation and synthesis results.
Warning
SpeakHDL does not support a std_logic_vector of length (1). Scalar values should be of type std_logic.
See also
USER_DEFS.vhd
TOP.vhd
TESTBENCH.vhd
SPEAKHDL_API_PKG.vhd