Merge pull request #845 from zapta/main

Added apio.ini option gtkwave-extra-options.

Author: zapta

.vscode/settings.json

@@ -170,6 +170,7 @@
         "pytest",
         "pyxx",
         "rankdir",
+        "rcvar",
         "readmemh",
         "realpath",
         "recursesubdirs",

apio/common/proto/apio.proto

@@ -111,8 +111,10 @@ message ApioEnvParams {
   repeated string yosys_synth_extra_options = 5;
   // The optional value of 'nextpnr-extra-options' option in apio.ini.
   repeated string nextpnr_extra_options = 6;
+  // The optional value of 'gtkwave-extra-options' option in apio.ini.
+  repeated string gtkwave_extra_options = 7;
   // The optional value of the 'constraint-file' option in apio.ini.
-  optional string constraint_file = 7 [default = ''];
+  optional string constraint_file = 8 [default = ''];
 }
 
 // Lint target specific params.

apio/common/proto/apio_pb2.py

@@ -27,19 +27,19 @@
 
 
 
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\napio.proto\x12\x11\x61pio.common.proto\"+\n\rIce40FpgaInfo\x12\x0c\n\x04type\x18\x01 \x02(\t\x12\x0c\n\x04pack\x18\x02 \x02(\t\"9\n\x0c\x45\x63p5FpgaInfo\x12\x0c\n\x04type\x18\x04 \x02(\t\x12\x0c\n\x04pack\x18\x05 \x02(\t\x12\r\n\x05speed\x18\x06 \x02(\t\"\x1f\n\rGowinFpgaInfo\x12\x0e\n\x06\x66\x61mily\x18\x04 \x02(\t\"\xda\x01\n\x08\x46pgaInfo\x12\x0f\n\x07\x66pga_id\x18\x01 \x02(\t\x12\x10\n\x08part_num\x18\x02 \x02(\t\x12\x0c\n\x04size\x18\x03 \x02(\t\x12\x31\n\x05ice40\x18\n \x01(\x0b\x32 .apio.common.proto.Ice40FpgaInfoH\x00\x12/\n\x04\x65\x63p5\x18\x0b \x01(\x0b\x32\x1f.apio.common.proto.Ecp5FpgaInfoH\x00\x12\x31\n\x05gowin\x18\x0c \x01(\x0b\x32 .apio.common.proto.GowinFpgaInfoH\x00\x42\x06\n\x04\x61rch\"I\n\tVerbosity\x12\x12\n\x03\x61ll\x18\x01 \x01(\x08:\x05\x66\x61lse\x12\x14\n\x05synth\x18\x02 \x01(\x08:\x05\x66\x61lse\x12\x12\n\x03pnr\x18\x03 \x01(\x08:\x05\x66\x61lse\"\xd9\x01\n\x0b\x45nvironment\x12\x13\n\x0bplatform_id\x18\x01 \x02(\t\x12\x12\n\nis_windows\x18\x02 \x02(\x08\x12\x36\n\rterminal_mode\x18\x03 \x02(\x0e\x32\x1f.apio.common.proto.TerminalMode\x12\x12\n\ntheme_name\x18\x04 \x02(\t\x12\x13\n\x0b\x64\x65\x62ug_level\x18\x05 \x02(\x05\x12\x12\n\nyosys_path\x18\x06 \x02(\t\x12\x14\n\x0ctrellis_path\x18\x07 \x02(\t\x12\x16\n\x0escons_shell_id\x18\x08 \x02(\t\"\xb5\x01\n\rApioEnvParams\x12\x10\n\x08\x65nv_name\x18\x01 \x02(\t\x12\x10\n\x08\x62oard_id\x18\x02 \x02(\t\x12\x12\n\ntop_module\x18\x03 \x02(\t\x12\x0f\n\x07\x64\x65\x66ines\x18\x04 \x03(\t\x12!\n\x19yosys_synth_extra_options\x18\x05 \x03(\t\x12\x1d\n\x15nextpnr_extra_options\x18\x06 \x03(\t\x12\x19\n\x0f\x63onstraint_file\x18\x07 \x01(\t:\x00\"\xc6\x01\n\nLintParams\x12\x14\n\ntop_module\x18\x01 \x01(\t:\x00\x12\x1c\n\rverilator_all\x18\x02 \x01(\x08:\x05\x66\x61lse\x12!\n\x12verilator_no_style\x18\x03 \x01(\x08:\x05\x66\x61lse\x12\x1a\n\x12verilator_no_warns\x18\x04 \x03(\t\x12\x17\n\x0fverilator_warns\x18\x05 \x03(\t\x12\x16\n\x07nosynth\x18\x06 \x01(\x08:\x05\x66\x61lse\x12\x14\n\x05novlt\x18\x07 \x01(\x08:\x05\x66\x61lse\"o\n\x0bGraphParams\x12\x37\n\x0boutput_type\x18\x01 \x02(\x0e\x32\".apio.common.proto.GraphOutputType\x12\x12\n\ntop_module\x18\x02 \x01(\t\x12\x13\n\x0bopen_viewer\x18\x03 \x02(\x08\"d\n\tSimParams\x12\x18\n\x0etestbench_path\x18\x01 \x01(\t:\x00\x12\x11\n\tforce_sim\x18\x02 \x02(\x08\x12\x12\n\nno_gtkwave\x18\x03 \x02(\x08\x12\x16\n\x0e\x64\x65tach_gtkwave\x18\x04 \x02(\x08\"B\n\x0e\x41pioTestParams\x12\x18\n\x0etestbench_path\x18\x01 \x01(\t:\x00\x12\x16\n\x0e\x64\x65\x66\x61ult_option\x18\x02 \x02(\x08\"&\n\x0cUploadParams\x12\x16\n\x0eprogrammer_cmd\x18\x01 \x01(\t\"\x8b\x02\n\x0cTargetParams\x12-\n\x04lint\x18\n \x01(\x0b\x32\x1d.apio.common.proto.LintParamsH\x00\x12/\n\x05graph\x18\x0b \x01(\x0b\x32\x1e.apio.common.proto.GraphParamsH\x00\x12+\n\x03sim\x18\x0c \x01(\x0b\x32\x1c.apio.common.proto.SimParamsH\x00\x12\x31\n\x04test\x18\r \x01(\x0b\x32!.apio.common.proto.ApioTestParamsH\x00\x12\x31\n\x06upload\x18\x0e \x01(\x0b\x32\x1f.apio.common.proto.UploadParamsH\x00\x42\x08\n\x06target\"\xcd\x02\n\x0bSconsParams\x12\x11\n\ttimestamp\x18\x01 \x02(\t\x12)\n\x04\x61rch\x18\x02 \x02(\x0e\x32\x1b.apio.common.proto.ApioArch\x12.\n\tfpga_info\x18\x03 \x02(\x0b\x32\x1b.apio.common.proto.FpgaInfo\x12/\n\tverbosity\x18\x04 \x01(\x0b\x32\x1c.apio.common.proto.Verbosity\x12\x33\n\x0b\x65nvironment\x18\x05 \x02(\x0b\x32\x1e.apio.common.proto.Environment\x12\x39\n\x0f\x61pio_env_params\x18\x06 \x02(\x0b\x32 .apio.common.proto.ApioEnvParams\x12/\n\x06target\x18\x07 \x01(\x0b\x32\x1f.apio.common.proto.TargetParams*@\n\x08\x41pioArch\x12\x14\n\x10\x41RCH_UNSPECIFIED\x10\x00\x12\t\n\x05ICE40\x10\x01\x12\x08\n\x04\x45\x43P5\x10\x02\x12\t\n\x05GOWIN\x10\x03*_\n\x0cTerminalMode\x12\x18\n\x14TERMINAL_UNSPECIFIED\x10\x00\x12\x11\n\rAUTO_TERMINAL\x10\x01\x12\x12\n\x0e\x46ORCE_TERMINAL\x10\x02\x12\x0e\n\nFORCE_PIPE\x10\x03*B\n\x0fGraphOutputType\x12\x14\n\x10TYPE_UNSPECIFIED\x10\x00\x12\x07\n\x03SVG\x10\x01\x12\x07\n\x03PNG\x10\x02\x12\x07\n\x03PDF\x10\x03')
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\napio.proto\x12\x11\x61pio.common.proto\"+\n\rIce40FpgaInfo\x12\x0c\n\x04type\x18\x01 \x02(\t\x12\x0c\n\x04pack\x18\x02 \x02(\t\"9\n\x0c\x45\x63p5FpgaInfo\x12\x0c\n\x04type\x18\x04 \x02(\t\x12\x0c\n\x04pack\x18\x05 \x02(\t\x12\r\n\x05speed\x18\x06 \x02(\t\"\x1f\n\rGowinFpgaInfo\x12\x0e\n\x06\x66\x61mily\x18\x04 \x02(\t\"\xda\x01\n\x08\x46pgaInfo\x12\x0f\n\x07\x66pga_id\x18\x01 \x02(\t\x12\x10\n\x08part_num\x18\x02 \x02(\t\x12\x0c\n\x04size\x18\x03 \x02(\t\x12\x31\n\x05ice40\x18\n \x01(\x0b\x32 .apio.common.proto.Ice40FpgaInfoH\x00\x12/\n\x04\x65\x63p5\x18\x0b \x01(\x0b\x32\x1f.apio.common.proto.Ecp5FpgaInfoH\x00\x12\x31\n\x05gowin\x18\x0c \x01(\x0b\x32 .apio.common.proto.GowinFpgaInfoH\x00\x42\x06\n\x04\x61rch\"I\n\tVerbosity\x12\x12\n\x03\x61ll\x18\x01 \x01(\x08:\x05\x66\x61lse\x12\x14\n\x05synth\x18\x02 \x01(\x08:\x05\x66\x61lse\x12\x12\n\x03pnr\x18\x03 \x01(\x08:\x05\x66\x61lse\"\xd9\x01\n\x0b\x45nvironment\x12\x13\n\x0bplatform_id\x18\x01 \x02(\t\x12\x12\n\nis_windows\x18\x02 \x02(\x08\x12\x36\n\rterminal_mode\x18\x03 \x02(\x0e\x32\x1f.apio.common.proto.TerminalMode\x12\x12\n\ntheme_name\x18\x04 \x02(\t\x12\x13\n\x0b\x64\x65\x62ug_level\x18\x05 \x02(\x05\x12\x12\n\nyosys_path\x18\x06 \x02(\t\x12\x14\n\x0ctrellis_path\x18\x07 \x02(\t\x12\x16\n\x0escons_shell_id\x18\x08 \x02(\t\"\xd4\x01\n\rApioEnvParams\x12\x10\n\x08\x65nv_name\x18\x01 \x02(\t\x12\x10\n\x08\x62oard_id\x18\x02 \x02(\t\x12\x12\n\ntop_module\x18\x03 \x02(\t\x12\x0f\n\x07\x64\x65\x66ines\x18\x04 \x03(\t\x12!\n\x19yosys_synth_extra_options\x18\x05 \x03(\t\x12\x1d\n\x15nextpnr_extra_options\x18\x06 \x03(\t\x12\x1d\n\x15gtkwave_extra_options\x18\x07 \x03(\t\x12\x19\n\x0f\x63onstraint_file\x18\x08 \x01(\t:\x00\"\xc6\x01\n\nLintParams\x12\x14\n\ntop_module\x18\x01 \x01(\t:\x00\x12\x1c\n\rverilator_all\x18\x02 \x01(\x08:\x05\x66\x61lse\x12!\n\x12verilator_no_style\x18\x03 \x01(\x08:\x05\x66\x61lse\x12\x1a\n\x12verilator_no_warns\x18\x04 \x03(\t\x12\x17\n\x0fverilator_warns\x18\x05 \x03(\t\x12\x16\n\x07nosynth\x18\x06 \x01(\x08:\x05\x66\x61lse\x12\x14\n\x05novlt\x18\x07 \x01(\x08:\x05\x66\x61lse\"o\n\x0bGraphParams\x12\x37\n\x0boutput_type\x18\x01 \x02(\x0e\x32\".apio.common.proto.GraphOutputType\x12\x12\n\ntop_module\x18\x02 \x01(\t\x12\x13\n\x0bopen_viewer\x18\x03 \x02(\x08\"d\n\tSimParams\x12\x18\n\x0etestbench_path\x18\x01 \x01(\t:\x00\x12\x11\n\tforce_sim\x18\x02 \x02(\x08\x12\x12\n\nno_gtkwave\x18\x03 \x02(\x08\x12\x16\n\x0e\x64\x65tach_gtkwave\x18\x04 \x02(\x08\"B\n\x0e\x41pioTestParams\x12\x18\n\x0etestbench_path\x18\x01 \x01(\t:\x00\x12\x16\n\x0e\x64\x65\x66\x61ult_option\x18\x02 \x02(\x08\"&\n\x0cUploadParams\x12\x16\n\x0eprogrammer_cmd\x18\x01 \x01(\t\"\x8b\x02\n\x0cTargetParams\x12-\n\x04lint\x18\n \x01(\x0b\x32\x1d.apio.common.proto.LintParamsH\x00\x12/\n\x05graph\x18\x0b \x01(\x0b\x32\x1e.apio.common.proto.GraphParamsH\x00\x12+\n\x03sim\x18\x0c \x01(\x0b\x32\x1c.apio.common.proto.SimParamsH\x00\x12\x31\n\x04test\x18\r \x01(\x0b\x32!.apio.common.proto.ApioTestParamsH\x00\x12\x31\n\x06upload\x18\x0e \x01(\x0b\x32\x1f.apio.common.proto.UploadParamsH\x00\x42\x08\n\x06target\"\xcd\x02\n\x0bSconsParams\x12\x11\n\ttimestamp\x18\x01 \x02(\t\x12)\n\x04\x61rch\x18\x02 \x02(\x0e\x32\x1b.apio.common.proto.ApioArch\x12.\n\tfpga_info\x18\x03 \x02(\x0b\x32\x1b.apio.common.proto.FpgaInfo\x12/\n\tverbosity\x18\x04 \x01(\x0b\x32\x1c.apio.common.proto.Verbosity\x12\x33\n\x0b\x65nvironment\x18\x05 \x02(\x0b\x32\x1e.apio.common.proto.Environment\x12\x39\n\x0f\x61pio_env_params\x18\x06 \x02(\x0b\x32 .apio.common.proto.ApioEnvParams\x12/\n\x06target\x18\x07 \x01(\x0b\x32\x1f.apio.common.proto.TargetParams*@\n\x08\x41pioArch\x12\x14\n\x10\x41RCH_UNSPECIFIED\x10\x00\x12\t\n\x05ICE40\x10\x01\x12\x08\n\x04\x45\x43P5\x10\x02\x12\t\n\x05GOWIN\x10\x03*_\n\x0cTerminalMode\x12\x18\n\x14TERMINAL_UNSPECIFIED\x10\x00\x12\x11\n\rAUTO_TERMINAL\x10\x01\x12\x12\n\x0e\x46ORCE_TERMINAL\x10\x02\x12\x0e\n\nFORCE_PIPE\x10\x03*B\n\x0fGraphOutputType\x12\x14\n\x10TYPE_UNSPECIFIED\x10\x00\x12\x07\n\x03SVG\x10\x01\x12\x07\n\x03PNG\x10\x02\x12\x07\n\x03PDF\x10\x03')
 
 _globals = globals()
 _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
 _builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'apio_pb2', _globals)
 if not _descriptor._USE_C_DESCRIPTORS:
   DESCRIPTOR._loaded_options = None
-  _globals['_APIOARCH']._serialized_start=2000
-  _globals['_APIOARCH']._serialized_end=2064
-  _globals['_TERMINALMODE']._serialized_start=2066
-  _globals['_TERMINALMODE']._serialized_end=2161
-  _globals['_GRAPHOUTPUTTYPE']._serialized_start=2163
-  _globals['_GRAPHOUTPUTTYPE']._serialized_end=2229
+  _globals['_APIOARCH']._serialized_start=2031
+  _globals['_APIOARCH']._serialized_end=2095
+  _globals['_TERMINALMODE']._serialized_start=2097
+  _globals['_TERMINALMODE']._serialized_end=2192
+  _globals['_GRAPHOUTPUTTYPE']._serialized_start=2194
+  _globals['_GRAPHOUTPUTTYPE']._serialized_end=2260
   _globals['_ICE40FPGAINFO']._serialized_start=33
   _globals['_ICE40FPGAINFO']._serialized_end=76
   _globals['_ECP5FPGAINFO']._serialized_start=78
@@ -53,19 +53,19 @@
   _globals['_ENVIRONMENT']._serialized_start=467
   _globals['_ENVIRONMENT']._serialized_end=684
   _globals['_APIOENVPARAMS']._serialized_start=687
-  _globals['_APIOENVPARAMS']._serialized_end=868
-  _globals['_LINTPARAMS']._serialized_start=871
-  _globals['_LINTPARAMS']._serialized_end=1069
-  _globals['_GRAPHPARAMS']._serialized_start=1071
-  _globals['_GRAPHPARAMS']._serialized_end=1182
-  _globals['_SIMPARAMS']._serialized_start=1184
-  _globals['_SIMPARAMS']._serialized_end=1284
-  _globals['_APIOTESTPARAMS']._serialized_start=1286
-  _globals['_APIOTESTPARAMS']._serialized_end=1352
-  _globals['_UPLOADPARAMS']._serialized_start=1354
-  _globals['_UPLOADPARAMS']._serialized_end=1392
-  _globals['_TARGETPARAMS']._serialized_start=1395
-  _globals['_TARGETPARAMS']._serialized_end=1662
-  _globals['_SCONSPARAMS']._serialized_start=1665
-  _globals['_SCONSPARAMS']._serialized_end=1998
+  _globals['_APIOENVPARAMS']._serialized_end=899
+  _globals['_LINTPARAMS']._serialized_start=902
+  _globals['_LINTPARAMS']._serialized_end=1100
+  _globals['_GRAPHPARAMS']._serialized_start=1102
+  _globals['_GRAPHPARAMS']._serialized_end=1213
+  _globals['_SIMPARAMS']._serialized_start=1215
+  _globals['_SIMPARAMS']._serialized_end=1315
+  _globals['_APIOTESTPARAMS']._serialized_start=1317
+  _globals['_APIOTESTPARAMS']._serialized_end=1383
+  _globals['_UPLOADPARAMS']._serialized_start=1385
+  _globals['_UPLOADPARAMS']._serialized_end=1423
+  _globals['_TARGETPARAMS']._serialized_start=1426
+  _globals['_TARGETPARAMS']._serialized_end=1693
+  _globals['_SCONSPARAMS']._serialized_start=1696
+  _globals['_SCONSPARAMS']._serialized_end=2029
 # @@protoc_insertion_point(module_scope)

apio/common/proto/apio_pb2.pyi

@@ -114,22 +114,24 @@ class Environment(_message.Message):
     def __init__(self, platform_id: _Optional[str] = ..., is_windows: bool = ..., terminal_mode: _Optional[_Union[TerminalMode, str]] = ..., theme_name: _Optional[str] = ..., debug_level: _Optional[int] = ..., yosys_path: _Optional[str] = ..., trellis_path: _Optional[str] = ..., scons_shell_id: _Optional[str] = ...) -> None: ...
 
 class ApioEnvParams(_message.Message):
-    __slots__ = ("env_name", "board_id", "top_module", "defines", "yosys_synth_extra_options", "nextpnr_extra_options", "constraint_file")
+    __slots__ = ("env_name", "board_id", "top_module", "defines", "yosys_synth_extra_options", "nextpnr_extra_options", "gtkwave_extra_options", "constraint_file")
     ENV_NAME_FIELD_NUMBER: _ClassVar[int]
     BOARD_ID_FIELD_NUMBER: _ClassVar[int]
     TOP_MODULE_FIELD_NUMBER: _ClassVar[int]
     DEFINES_FIELD_NUMBER: _ClassVar[int]
     YOSYS_SYNTH_EXTRA_OPTIONS_FIELD_NUMBER: _ClassVar[int]
     NEXTPNR_EXTRA_OPTIONS_FIELD_NUMBER: _ClassVar[int]
+    GTKWAVE_EXTRA_OPTIONS_FIELD_NUMBER: _ClassVar[int]
     CONSTRAINT_FILE_FIELD_NUMBER: _ClassVar[int]
     env_name: str
     board_id: str
     top_module: str
     defines: _containers.RepeatedScalarFieldContainer[str]
     yosys_synth_extra_options: _containers.RepeatedScalarFieldContainer[str]
     nextpnr_extra_options: _containers.RepeatedScalarFieldContainer[str]
+    gtkwave_extra_options: _containers.RepeatedScalarFieldContainer[str]
     constraint_file: str
-    def __init__(self, env_name: _Optional[str] = ..., board_id: _Optional[str] = ..., top_module: _Optional[str] = ..., defines: _Optional[_Iterable[str]] = ..., yosys_synth_extra_options: _Optional[_Iterable[str]] = ..., nextpnr_extra_options: _Optional[_Iterable[str]] = ..., constraint_file: _Optional[str] = ...) -> None: ...
+    def __init__(self, env_name: _Optional[str] = ..., board_id: _Optional[str] = ..., top_module: _Optional[str] = ..., defines: _Optional[_Iterable[str]] = ..., yosys_synth_extra_options: _Optional[_Iterable[str]] = ..., nextpnr_extra_options: _Optional[_Iterable[str]] = ..., gtkwave_extra_options: _Optional[_Iterable[str]] = ..., constraint_file: _Optional[str] = ...) -> None: ...
 
 class LintParams(_message.Message):
     __slots__ = ("top_module", "verilator_all", "verilator_no_style", "verilator_no_warns", "verilator_warns", "nosynth", "novlt")

apio/managers/project.py

@@ -90,6 +90,10 @@ class EnvOptionSpec:
         name="nextpnr-extra-options",
         is_list=True,
     ),
+    "gtkwave-extra-options": EnvOptionSpec(
+        name="gtkwave-extra-options",
+        is_list=True,
+    ),
     "constraint-file": EnvOptionSpec(
         name="constraint-file",
     ),

apio/managers/scons_manager.py

@@ -293,6 +293,9 @@ def construct_scons_params(
                 nextpnr_extra_options=apio_ctx.project.get_list_option(
                     "nextpnr-extra-options", None
                 ),
+                gtkwave_extra_options=apio_ctx.project.get_list_option(
+                    "gtkwave-extra-options", None
+                ),
                 constraint_file=apio_ctx.project.get_str_option(
                     "constraint-file", None
                 ),

apio/scons/plugin_util.py

@@ -401,17 +401,21 @@ def action_func(
 
 
 def gtkwave_target(
-    api_env: ApioEnv,
+    apio_env: ApioEnv,
     target_name: str,  # always 'sim'
     vcd_file_target: NodeList,
     testbench_info: TestbenchInfo,
     sim_params: SimParams,
+    gtkwave_extra_options: Optional[List[str]],
 ) -> List[Alias]:
     """Construct a target to launch the QTWave signal viewer.
     vcd_file_target is the simulator target that generated the vcd file
     with the signals. Returns the new targets.
     """
 
+    # pylint: disable=too-many-arguments
+    # pylint: disable=too-many-positional-arguments
+
     # -- Construct the list of actions.
     actions = []
 
@@ -452,31 +456,31 @@ def create_default_gtkw_file(
         # -- The time penalty is negligible.
         # -- With the stock oss-cad-suite windows package, this is done in the
         # -- environment.bat script.
-        if api_env.is_windows:
+        if apio_env.is_windows:
             actions.append("gdk-pixbuf-query-loaders --update-cache")
 
         # -- The actual wave viewer command.
-        gtkwave_cmd = [
-            "gtkwave",
-            "--rcvar",
-            "splash_disable on",
-            "--rcvar",
-            "do_initial_zoom_fit 1",
-            vcd_path,
-            gtkw_path,
-        ]
+        gtkwave_cmd = ["gtkwave"]
+        # -- NOTE: Users can override these rcvars by adding the desired
+        # -- rcvar options in apio.ini gtkwave-extra-options which will win
+        # -- since they will appear later in the command line.
+        gtkwave_cmd.append("--rcvar=splash_disable on")
+        gtkwave_cmd.append("--rcvar=do_initial_zoom_fit 1")
+        if gtkwave_extra_options:
+            gtkwave_cmd.extend(gtkwave_extra_options)
+        gtkwave_cmd.extend([vcd_path, gtkw_path])
 
         # -- Handle the case where gtkwave is run as a detached app, not
         # -- waiting for it to close and not showing its output.
         if sim_params.detach_gtkwave:
-            gtkwave_action = detached_action(api_env, gtkwave_cmd)
+            gtkwave_action = detached_action(apio_env, gtkwave_cmd)
         else:
             gtkwave_action = subprocess.list2cmdline(gtkwave_cmd)
 
         actions.append(gtkwave_action)
 
     # -- Define a target with the action(s) we created.
-    target = api_env.alias(
+    target = apio_env.alias(
         target_name,
         source=vcd_file_target,
         action=actions,

apio/scons/scons_handler.py

@@ -349,7 +349,7 @@ def _register_apio_sim_target(self, synth_srcs, test_srcs):
             builder_id=TESTBENCH_RUN_BUILDER,
             target=testbench_info.build_testbench_name,
             sources=[sim_out_target],
-            always_build=sim_params,
+            always_build=sim_params.force_sim,
         )
 
         # -- The top level "sim" target.
@@ -359,6 +359,7 @@ def _register_apio_sim_target(self, synth_srcs, test_srcs):
             sim_vcd_target,
             testbench_info,
             sim_params,
+            params.apio_env_params.gtkwave_extra_options,
         )
 
     def _register_apio_test_target(self, synth_srcs, test_srcs):

docs/cmd-apio-sim.md

@@ -18,6 +18,17 @@ signals, modify them in GTKWave and save your configuration using the
 `File > Write Save File` menu command. The `apio sim` command will never
 overwrite a `.gtkw` files that were saved in this way.
 
+The command line that used to invoke the signal viewer `gtkwave` can be 
+customized using the `apio.ini` option `gtkwave-extra-options`. 
+For example, the option below disables the var `do_initial_zoom_fit` to prevent
+gtkwave from forcing a fully-out zoom upon start.
+
+```
+[env:default]
+gtkwave-extra-options =
+    --rcvar=do_initial_zoom_fit 0
+```
+
 The `apio sim` command defines the macro `APIO_SIM=1`, which allows failed
 assertions to skip the `$fatal` call. This lets the simulation continue and
 display faulty signals in the GTKWave viewer.

docs/project-file.md

@@ -169,6 +169,19 @@ format-verible-options =
 For the list of the Verible formatter options, run the command `apio 
 raw -- verible-verilog-format --helpfull`
 
+### gtkwave-extra-options
+
+The optional `gtkwave-extra-options` string list option allows adding options to the
+gtkwave command that that is invoked by the `apio sim`.
+For example, the option below disables the var `do_initial_zoom_fit` to prevent
+gtkwave from forcing a fully-out zoom upon start.
+
+```
+[env:default]
+gtkwave-extra-options =
+    --rcvar=do_initial_zoom_fit 0
+```
+
 ### nextpnr-extra-options
 
 The optional `nextpnr-extra-options` string list option allows adding options to the