Naming Conventions

Todo

Write an intruduction paragraph for this page.

Root Directory Overview (PoCRoot)

The PoC-Library is structured into several sub-directories, naming the purpose of the directory like src for sources files or tb for testbench files. The structure within these directories is most likely the same and based on PoC’s sub-namespace tree. PoC’s installation directory is also referred to as PoCRoot.

• lib

  Third party libraries like Coctb, OSVVM or VUnit are shipped in this folder. The external library is stored in a sub directory named like the library. If a library is available as a Git submodule, then it is linked as a submodule for better version tracking.

• netlist

  This is the output directory for pre-configured netlists, synthesized by PoC. Netlists and related constaint files are the result of IP core synthesis flows, either from PoC’s source files or from vendor specific IP core files like *.xco files from Xilinx Core Generator. Generated IP cores are stored in device sub-directories, because most netlists formats are device specific. For example the IP core PoC.arith.prng created from source file src\arith\arith_prng.vhdl generated for a Kintex-7 325T mounted on a KC705 board will be copied to netlist\XC7K325T-2FFG900\arith\arith_prng.ngc if Xilinx ISE XST is used for synthesis.

• py

  The supporting Python infrastructure, the configuration files and the IP core ‘database’ is stored in this directory.

• sim

  Some of PoC’s testbenches are shipped with pre-configured waveform views/ waveform configuration files for selected simulators or waveform viewers. If a testbench is launched in GUI mode (--gui) and a waveform view for the choosen simulator is found, it’s loaded as the default view.

• src

  The source files of PoC’s IP cores are stored in this directory. The IP cores are grouped by their sub-namespace into sub-directories according to the sub-namespace tree. See the paragraph below, for how IP cores are named and how PoC core names map to the sub-namespace hierachy and the resulting sub-namespace directory structure.

• tb

  PoC is shipped with testbenches. All testbenches are categorized and stored in sub-directories like the IP core, which is tested.

• tcl

  Supporting Tcl files.

• temp

  A pre-created temporary directors for various tool’s intermediate outputs. In case of errors in a used vendor tool or in PoC’s infrastructure, this directory contains intermediate files, log files and report files, which can be used to analyze the error.

• tools

  This directory contains miscelaneous files or scripts for external tools like emacs, git or text editor syntax highlighting files.

• ucf

  Pre-configured constraint files (*.ucf, *.xdc, *.sdc) for many FPGA boards, containing physical (pin, placement) and timing constraints.

• xst

  Configuration files to synthesize PoC modules with Xilinx XST into a netlist.

Namespaces and Modules

Namespaces

PoC uses namespaces and sub-namespaces to categorize all VHDL and Verilog modules. Despite VHDL doesn’t support sub-namespaces yet, PoC already uses sub-namespaces enforced by a strict naming schema.

Rules:
1. Namespace names are lower-case, underscore free, valid VHDL identifiers.
2. A namespace name is unique, but can be part of a entity name.

Module Names

Module names are prefixed with its parents namespace name. A module name can contain underscores to denote implementation variants of a module.

Rules:
3. Modul names are valid VHDL identifiers prefixed with its parent namespace’s name.
4. The first part of module name must not contain the parents namespace name.

Example 1 - PoC.fifo.cc_got

For example a FIFO module with a common clock interface and a got semantic is named PoC.fifo.cc_got (fully qualified name). This name can be split at every dot and underscore sign, resulting in the following table of name parts:

PoC	fifo	cc	got
Root Namespace	Sub-Namespace	Common Clock Interface	Got Semantic

Because PoC.fifo.cc_got refers to an IP core, the source file is located in the <PoCRoot>\src directory. The (sub-)namespace of the PoC entity is fifo, so it’s stored in the sub-directory fifo. The file name cc_got FIFO is prefixed with the last sub-namespace: In this case fifo_. This is summarized in the following table:

Property	Value
Fully Qualified Name	PoC.fifo.cc_got
VHDL entity name	fifo_cc_got
File name	fifo_cc_got.vhdl
IP Core Description File	\src\fifo\fifo_cc_got.files
Source File Location	\src\fifo\fifo_cc_got.vhdl
Testbench Location	\tb\fifo\fifo_cc_got_tb.vhdl
Testbench Description File	\tb\fifo\fifo_cc_got_tb.files
Waveform Description Files	\sim\fifo\fifo_cc_got_tb.*

Other implementation variants are:

• _dc – dependent clock / related clock

• _ic – independent clock / cross clock

• _got_tempgot – got interface extended by a temporary got interface

• _got_tempput – got interface extended by a temporary put interface

Example 2 - PoC.mem.ocram.tdp

PoC	mem	ocram	tdp
Root Namespace	Sub-Namespace	Sub-Namespace	True-Dual-Port

Property	Value
Fully Qualified Name	PoC.mem.ocram.tdp
VHDL entity name	ocram_tdp
File name	ocram_tdp.vhdl
IP Core Description File	\src\mem\ocram\ocram_tdp.files
Source File Location	\src\mem\ocram\ocram_tdp.vhdl
Testbench Location	\tb\mem\ocram\ocram_tdp_tb.vhdl
Testbench Description File	\tb\mem\ocram\ocram_tdp_tb.files
Waveform Description Files	\sim\mem\ocram\ocram_tdp_tb.*

Note: Not all sub-namespace parts are include as a prefix in the name, only the last one.

Signal Names

Todo

No documentation available.