fpgasm / fpgasm

A low-level hierarchical netlist assembler for FPGAs

What is FPGASM? (WORK IN PROGRESS)

FPGAsm is an experimental low-level hierarchical language for constructing Xilinx FPGA netlists.

FPGAsm attempts to minimize build time, and provide an alternative to Verilog and VHDL. It encourages modularity and reusability, and provides a tool for exploration and fuller understanding of the underlying hardware, leading to better utilization and personal satisfaction.

FPGAsm's minimal syntax encourages the creation of small, reusable modules (which consist of other modules and wiring). Low-level modules interface with FPGA hardware (IOBs, LUTs, memories, etc). These are used to construct higher-level modules (ALUs, bus latches, memory controllers); these in turn can form working systems, represented by the top module. Each module may be independently tested and characterized,

FPGAsm allows you to build modular hierarchical netlists, acting as a front-end of an FPGA toolchain. FPGAsm is a manual equivalent of a synthethis, mapping and placement tool. It relies on a back-end (currently Xilinx ISE 14.7) for final routing and bitstream generation. FPGAsm uses XDL as its output format.

Release notes

2021: I am back at it. Updated the code to handle Artix-100 devices.

• Separated xdlrc load from source. Do not include xdlrc files - instead, rename the xdlrc to 'device.xdlrc' (or symlink it) in the invocation directory, or specify the file as the third parameter.
• removed many (not all) memory leaks;
• increased size of name buffers (caused crashes with Artix)
• made a provision for cfgs like IOBUF:something: For instance, if you want: AAA:bbb: the FPGAsm syntax is AAA:_bbb (undrescore removed, colon appended).

Who is it for?

FPGAsm is an ideal exploration tool for a hardware hacker. If you want to truly understand and exploit the Xilinx FPGA architecture, give it a try.

Unlike HDLs, FPGAsm provides direct and unobstructed access to the FPGA hardware grid. FPGAsm does not infer circuits - it does exactly what you ask for. Instead of constraining or annotating your code and hoping it works, you are in complete control. With this comes the responsibility - you must understand the underlying hardware. Luckily, FPGAsm is the ultimate exploration tool, allowing you to construct quick and repeatable experiments with rapid turnaround (seconds on smaller FPGAs).

What does the code look like?

A simple module example:

//================================    
	// Digilent Spartan S3 Demo board
	// 4 pushbuttons
	//================================
	Buttons( output( OUT[4]){           /*Bus of 4 wires */) 
	  button0 InSimple loc:M13;         //M13 is the FPGA pin - no ucf files needed.
	  wire button0's OUT to my OUT[0] ; //see module 'InSimple' - it has an OUT pin
	  button1 InSimple loc:M14;
	  wire button1 OUT to my OUT[1] ;
	  button2 InSimple loc:L13;
	  wire her OUT to my OUT[2] ;       //her refers to button2
	  button3 InSimple loc:L14;
	  wire her OUT to my OUT[3] ;       //now her refers to button3
	}

Note that InSimple is also a module. The module Buttons may now be instantiated in a higher level circuit, and its outputs may be wired to other circuits.

Development Flow:

A command-line build environment is provided. FPGAsm files (.fa extension) are processed as follows:

in    tool        out
--    ----        ---
.fa   fpgasm      .ncd (unrouted)
.ncd  PAR         .ncd (routed)
.ncd  BITGEN      .bit
.bit  IMPACT      FPGA

Currently FPGAsm uses Xilinx XDL and therefore is bound to ISE 14.7. FPGAsm code is translated to XDL, which is converted to NCD and routed using Xilinx tools. FPGAsm also needs an .xdlrc file (generated by Xilinx tools) in order to get a total description of the target FPGA. You need to install ISE 14.7 in order to use FPGAsm. In the future, other backends may become available.

FPGAsm itself is nearly instant. The total build time is dependent on the Xilinx place/route and bitgen code, and is a few seconds for Spartan 3 and under 1 minute for large Artix 100 chips..

Installation

Prerequisites

Xilinx ISE 14.7 must be installed, and configured to work from the command line. Make sure to source settings64.sh. Test by typing 'par' on the command line.

Build

A normal c++ build environment should be sufficient to build fpgasm with make. Either sudo make install will copy the binary to /bin, or move the executable fpgasm to to a directory in your PATH.

Command Line Parameters

Executing fpgasm without any parameters should output the copyright notice and usage information:

    Usage: fpgasm <inname.fa> <outname.xdl> [<device>.xdlrc]

<inname.fa>     source fpgasm file
<outname>.xdl   output XDL file
<device>.xdlrc  optional device description filename.  If omitted, fpgasm
                will try to open 'device.xdlrc' in the current directory.

How to really use it

• FPGAsm blog for details, commentary and updates

Outdated but useful, for now:

• the wiki for more information.
• fpgasm-test test code

References

OLD version:

See other repos for tools and code

• fpgasm-test test code
• fpgasm-xcfg visual configuration string tool