Skip to content

Pragmas

Jump to bottom
Julian Kemmerer edited this page May 22, 2023 · 32 revisions

Alot of functionality is automatically generated based on C design patterns/macros/special headers.

But - essentially being a custom C compiler - there are some pragmas involved:

FPGA Part (synthesis+place and route tool)

  • PART : The FPGA part string as required by the by synthesis+place and route tool. Ex.
    • #pragma PART "xc7a35ticsg324-1l" // Arty Artix 7

Main / Top Level Functions

  • MAIN_MHZ : Function is a top level main instance with operating frequency in megahertz. Ex.
    • #pragma MAIN_MHZ my_main 100.0
  • MAIN : Function is a top level main instance with inferred operating frequency. Ex.
    • #pragma MAIN my_main
  • MAIN_SYN_MHZ : Function is a top level main instance with synthesis target frequency in megahertz. Ex.
    • #pragma MAIN_SYN_MHZ my_main 150.0
    • Often some fixed percentage higher than MAIN_MHZ
  • MAIN_GROUP : Main function is a top level main instance belonging to a named clock group. Ex.
    • #pragma MAIN_GROUP my_main my_group

Function Definitions

  • FUNC_MULT_STYLE : Function multiplier style. Primarily used to switch off DSP primitive inference. Ex.
    • #pragma FUNC_MULT_STYLE my_mult_func fabric // default: inferred
  • FUNC_MARK_DEBUG : All registers used by the function are marked with the VHDL mark_debug attribute. Ex.
    • #pragma FUNC_MARK_DEBUG my_func
  • FUNC_WIRES : Function assumed to synthesize to wires - not synthesized for comb. logic delay estimates. Ex.
    • #pragma FUNC_WIRES my_func
  • FUNC_BLACKBOX : Function replaced with dummy IO registers up until the final user files are generated.
    • The PipelineC tool never sees a real synthesized version of this function.
    • Primarily used for deferring the synthesis/actual use of module internals until user is doing final implementation runs elsewhere.
    • Great for IP existing elsewhere/in another flow. Ex.
    • #pragma FUNC_BLACKBOX my_func

Globally Visible Wires

  • ID_INST : Associated an identifier (typically clock crossing/wires) and an instance name (see INST_NAME pragma).
    • #pragma ID_INST leds my_inst[3]
  • ASYNC_WIRE : Marks a wire as being async, untimed. Mostly used to turn off clock crossing functionality.
    • #pragma ASYNC_WIRE my_wire
  • CLK_MHZ : Marks a wire as being a clock with a specific frequency. Used for 'promoting' user wires to clock signals the tool can work with. Good idea to mark as ASYNC_WIRE as well unless otherwise needed.
    • #pragma CLK_MHZ my_clock_wire 100.0
  • INST_ARRAY : Associate an instance variable used multiple times with an array variable used once

Wires in Functions

Functions Calls (Submodule Instances)

  • INST_NAME : Give the next function call a specific instance name. Can use loop iterators for unique names if needed.
    • Used for connecting to globally scoped things.
#pragma MAIN my_main
void my_main()
{
  uint32_t i;
  for(i=0;i<N;i+=1)
  {
    #pragma INST_NAME my_inst i
    some_func();
    // Full instance name for some_func
    // is ex. i=3 "my_main/my_inst[3]"
  }
}

Variables

  • MARK_DEBUG : Mark a static local variable (register) with the VHDL mark_debug attribute. Ex.
    • #pragma MARK_DEBUG my_static_local_var
  • VAR_VHDL_INIT : Initialize VHDL variable/register with string from a text file.
    • Useful for BRAM init files.
static color_12b_t an_image[W*H];
#pragma VAR_VHDL_INIT an_image /path/to/an_image_init_text.vhd
Clone this wiki locally