Parameterize SCons file based on apio settings

[s-ol]

The SCons file is quite "magical" and undocumented at the moment. I needed to find it to understand these points for example:

• how is a PCF file located? which is chosen if there are multiple?
• how are testbench files recognized and treated?
• how are verilog source files recognized and treated?

IMO the second two should be documented in the docs for apio sim and apio build respectively.
These informations are crucial for newcomers to start using apio, whether they have worked with FPGAs or icestorm before or not.

For solving the first issue, I would propose parameterizing the SCons file as follows:

• pcf - path to PCF file, default: glob *.pcf, error if multiple
• testbench - path to main testbench file, default: glob *_tb.v, error if multiple

these settings should be documented for and set in apio.ini. (btw: there is no documentation about apio.ini settings currently)

[roman3017]

• how are verilog source files recognized and treated?

I also find this request useful. It would be also nice if there is a way to specify the source files order. The current order seems to be alphabetical, which may not work in some cases. An example is building picosoc. One needs to list picosoc.v before picorv32.v so one cannot use apio build as is. The current workarounds are using Makefile or using apio raw or modifying SConstruct script or renaming the original files. Maybe having a possibility to have an ordered list of all sources in a config file could be beneficial. If the ordered list of sources is missing then existing alphabetical order of all sources could work.

[zapta]

@roman3017, I moved your request to a new issue here #452

[zapta]

@s-ol, here are some info, based on the next apio release (currently in dev stage).

• Apio looks for *.pcf files and expects to find exactly one. Otherwise it prints an error message and exist.

• Source file looks like my_module.v while testbench file look like my_module_tb.v. The command 'apio test' tests all the testbenches it finds but you can restrict it to a single testbench file you specify. The command 'apio sim' expects a specification of the testbench to use using the --testbench option.

• apio build uses all the source files and ignores the testbench files.

$ apio test -h
Usage: apio test [OPTIONS] [TESTBENCH_FILE]

  The sim command simulates one or all the testbenches in the project and is
  useful for automatic unit testing of the code. Testbenches are expected to
  exist with the $fatal directive if any error is detected. The commands is
  typically used in the root directory of the project that contains the
  apio.ini.

  Examples
    apio test                 # Run all *_tb.v testbenches.
    apio test my_module_tb.v  # Run a single testbench

  For a sample testbench that is compatible with apio see the example at
  https://github.com/FPGAwars/apio-examples/tree/master/upduino31/testbench

  [Hint] To simulate the testbench with a graphical visualizaiton of the
  signals see the apio sim command.

Options:
  -p, --project-dir path  Set the root directory for the project.
  -h, --help              Show this message and exit.

$ apio sim -h
Usage: apio sim [OPTIONS] TESTBENCH

  The sim command simulates a testbench file and shows the simulation results
  a GTKWave graphical window. The commands is typically used in the root
  directory of the project that contains the apio.ini file and it accepts the
  testbench file name as an argument. For example:

  Example:
    apio sim my_module_tb.v

  The sim command defines the macros VCD_OUTPUT and INTERACTIVE_SIM that can
  be used by the testbench. For a sample testbench that uses those macro see
  the example at https://github.com/FPGAwars/apio-
  examples/tree/master/upduino31/testbench

  [Hint] when you configure the signals in GTKWave, you can save the
  configuration for future invocations.

Options:
  -p, --project-dir path  Set the root directory for the project.
  -h, --help              Show this message and exit.

$ apio build -h
Usage: apio build [OPTIONS]

  The build command reads the project source files and generates a bitstream
  file that you can uploaded to your FPGA. The commands is typically used in
  the root directory of the project that contains the apio.ini file.

  Examples:
    apio build
    apio build -v

  [Note] Flags marked with [DEPRECATED] are not recomanded for use. For
  project configuration, use an apio.ini project file and if neaded, project
  specific 'boards.json' and 'fpga.json' definition files.

Options:
  -p, --project-dir path  Set the root directory for the project.
  -v, --verbose           Show detailed output.
  --verbose-yosys         Show detailed yosys output.
  --verbose-pnr           Show detailed pnr output.
  -t, --top-module name   [DEPRECATED] Set the top level module name.
  -b, --board str         [DEPRECATED] Set the board.
  --fpga str              [DEPRECATED] Set the FPGA.
  --size str              [DEPRECATED] Set the FPGA size (1k/8k).
  --type str              [DEPRECATED] Set the FPGA type (hx/lp).
  --pack str              [DEPRECATED] Set the FPGA package.
  -h, --help              Show this message and exit.

[zapta]

Closing this issue. If you have further questions or comments please reopen.