LINK File

LINK file is one of the design file types. It contains whole information of integration design, and its content is mainly divided into 6 parts:

1. Constant definition

2. Leaf module definition

3. Shell module definition

4. Hierarchy definition

5. Shell module port definition

6. Connection information

LINK file is used by LinkFab, but user also can modify it manually. So to understand its format is also important to LinkFab users.

Comment

Comment can be used in LINK file, it starts with ‘#’, and till end of the line, just like in other languages.

Constant

Constant is actually a parameter. It’s ususally used to define the width of a bus port, in case a bus port’s width could be changed in future, then change the constant is much more convinient.

To define a constant:

constant BUSWIDTH 32

To use a constant:

bus in  data1(BUSWIDTH:0)
bus out data2(BUSWIDTH-1:0)

Leaf Module

Leaf modules are the end of design hierarchy, they are loaded from design source code. To make LinkFab find the module and its file, some information need to be provided:

instance <unit-name> \
    module      <module-name> \
    instname    <instance-name> \
    arch        <arch-name> \
    conf        <conf-name> \
    path        <path> \
    incdirs     <path1>,<path2>,... \
    preload     <header-file1>,<header-file2>,...

Unit name is used by LinkFab, it should be globally uniq, and it can be same as moudle name or totally different.

Keyword module is used to specify the language of source code is VERILOG, to specify VHDL, use keyword entity instead. Module name must be same as in source code. This item can be ignored when module name is same with unit name.

The instname is for the instance’s name in finally generated code, if it’s the same as unit name, this item can be ignored.

The arch and conf are only for VHDL modules, to guide LinkFab to find the file.

The path tells where to find the module file. By convention, the module filename should be same with the module name. If this is not the case, make a symbol link to that.

The incdirs specifies search paths for verilog include files, if “`include” is found in the source code. Multiple paths can be specified, separated by comma.

The preload is similar with incdirs for verilog, but included files are not specified in source code by “`include” directives. With this LinkFab will read in preloading files first before parsing module file. Multiple preloading files are also supported, separated by comma.

Shell Module

Shell modules are those not leaf modules, they have child modules under them. Shell modules need to be generated finally, some information also need to guide LinkFab for code generation.

generate verilog <module-name> \
    instname <instance-name> \
    arch     <arch-name> \
    conf     <conf-name> \
    path     <path>

This statement create a verilog shell module, to generate VHDL module, use vhdl keyword instead. The path is the output folder, and the generated filename is <module-name>.v, when VHDL module is specified, 3 files need to be generated, entity file, architecture file, configuration file, filenames will be: <module-name>-e.vhd, <module-name>-<arch-name>-a.vhd, <module-name>-<conf-name>-c.vhd. The arch and conf are only for VHDL modules, to specify the architecture name and configuration name, as well as part of the generated filename. The instname is the instance’s name in the generated code.

Hierarchy

After all modules are loaded or created, they need to be bound together by hierarchy definition. Hierarchy tells a shell module which child modules it should contain, either other shell modules or leaf modules. Which means every module should have a parent module, except the top shell module.

hierarchy <shell-module> = <module1> <module2> ...
or
hierarchy <shell-module> = <module1>
hierarchy <shell-module> = <module2>

Port Define

Shell module’s port can be defined, especially the top shell module.

pin in  top.clk_i
pin out top.flag_o
bus out top.data_o(31:0)
bus in  top.addr_i(15:0)
pin in  middle.clk_i

Keyword pin is used for a single port, while bus is for bus port. IO is specified by keyword in | out | inout. A bus port’s size can be specified with (high:low).

Normally the middle shell modules’ ports are automatically generated by LinkFab, but user can rename some of them by creating them ahead of time, then connect them.

Connection

Connection is the main part of LINK file, and to make this region readable to users, it’s divided into 3 parts:

1. Normal connection part

2. Tie connection part

3. Open connection part

Each connection part is further divided into modules parts, sorted by module name.

Connection information is made up of a driver and a load or serval loads, like:

from modA.portA         to {modB.portB}             # one load
from modA.portA         to {modB.portB modC.portC}  # two loads
from modD.portD         to {modE.portE(2)}
from modF.portF(3:1)    to {modG.portG(7:5)}

For tie connection, the driver is a VHDL style constant or some keywords like all_0, all_1:

from '0'                to {modA.portA}
from '1'                to {modB.portB(5)}
from "0001"             to {modC.portC(3:0)}
from "1010101"          to {modD.portD}

from "all_0"            to {modE.portE}
from "all_1"            to {modF.portF(31:16)}

For open connection, the load is empty, like:

from modA.portA         to {}

Review state can be specified in the comment section, in form of *CONFIRMED*.

from '0'                to {modA.portA}     # *CONFIRMED*