utils/vlog: Improve style and documentation in yosys.run Signed-off-by: David Shah <davey1576@gmail.com>
diff --git a/yosys/run.py b/yosys/run.py index f34ad57..0b475ea 100755 --- a/yosys/run.py +++ b/yosys/run.py
@@ -4,26 +4,45 @@ import yosys.utils def get_yosys(): - return os.getenv('YOSYS', "yosys") + """Return how to execute Yosys: the value of $YOSYS if set, otherwise just + `yosys`.""" + return os.getenv("YOSYS", "yosys") def get_output(params): + """Run Yosys with given command line parameters, and return stdout as a string""" cmd = [get_yosys()] + params return subprocess.check_output(cmd).decode("utf-8") defines = [] def add_define(defname): + """Add a Verilog define to the list of defines to set in Yosys""" defines.append(defname) def get_defines(): + """Return a list of set Verilog defines, as a list of arguments to pass to Yosys `read_verilog`""" return " ".join(["-D" + _ for _ in defines]) def commands(commands, infiles = []): + """Run a given string containing Yosys commands + + Inputs + ------- + commands : string of Yosys commands to run + infiles : list of input files + """ commands = "read_verilog %s %s; " % (get_defines(), " ".join(infiles)) + commands params = ["-q", "-p", commands] return get_output(params) def script(script, infiles = []): + """Run a Yosys script given a path to the script + + Inputs + ------- + script : path to Yosys script to run + infiles : list of input files + """ params = ["-q", "-s", script] + infiles return get_output(params) @@ -42,7 +61,7 @@ prep_opts = "-flatten" if flatten else "" json_opts = "-aig" if aig else "" if mode is not None: - mode_str = "chparam -set MODE \"%s\" %s; " % (mode, mode_mod) + mode_str = 'chparam -set MODE "%s" %s; ' % (mode, mode_mod) else: mode_str = "" cmds = "%sprep %s; write_json %s" % (mode_str, prep_opts, json_opts) @@ -54,7 +73,14 @@ def extract_pin(module, pstr, _regex=re.compile(r"([^/]+)/([^/]+)")): """ - Extract the pin from a line of the result of a Yosys select command + Extract the pin from a line of the result of a Yosys select command, or + None if the command result is irrelevant (e.g. does not correspond to the + correct module) + + Inputs + ------- + module: Name of module to extract pins from + pstr: Line from Yosys select command (`module/pin` format) """ m = re.match(r"([^/]+)/([^/]+)", pstr) if m and m.group(1) == module: @@ -68,6 +94,12 @@ """ Run a Yosys select command (given the expression and input files) on a module and return the result as a list of pins + + Inputs + ------- + infiles: List of Verilog source files to pass to Yosys + module: Name of module to run command on + expr: Yosys selector expression for select command """ """TODO: All of these functions involve a fairly large number of calls to Yosys @@ -91,13 +123,33 @@ def get_combinational_sinks(infiles, module, innet): """Return a list of output ports which are combinational sinks of a given - input.""" + input. + + Inputs + ------- + infiles: List of Verilog source files to pass to Yosys + module: Name of module to run command on + innet: Name of input net to find sinks of + """ return do_select(infiles, module, "%s %%coe* o:* %%i %s %%d" % (innet, innet)) def list_clocks(infiles, module): - """Return a list of clocks in the module""" + """Return a list of clocks in the module + + Inputs + ------- + infiles: List of Verilog source files to pass to Yosys + module: Name of module to run command on + """ return do_select(infiles, module, "c:* %x:+[CLK] a:CLOCK=1 %u c:* %d") def get_clock_assoc_signals(infiles, module, clk): - """Return the list of signals associated with a given clock.""" + """Return the list of signals associated with a given clock. + + Inputs + ------- + infiles: List of Verilog source files to pass to Yosys + module: Name of module to run command on + clk: Name of clock to find associated signals + """ return do_select(infiles, module, "select -list %s %%x* i:* o:* %%u %%i a:ASSOC_CLOCK=%s %%u %s %%d" % (clk, clk, clk))