Updated command-reference-manual.tex

manual/command-reference-manual.tex

@@ -21,6 +21,9 @@ library to a target architecture.
         but keeps using yosys's internal gate library. This option is ignored if
         the -script option is also used.
 
+    -constr <file>
+        pass this file with timing constraints to ABC
+
     -lut <width>
         generate netlist using luts of (max) the specified width.
 
@@ -34,6 +37,28 @@ This pass does not operate on modules with unprocessed processes in it.
 [1] http://www.eecs.berkeley.edu/~alanmi/abc/
 \end{lstlisting}
 
+\section{add -- add objects to the design}
+\label{cmd:add}
+\begin{lstlisting}[numbers=left,frame=single]
+    add <command> [selection]
+
+This command adds objects to the design. It operates on all fully selected
+modules. So e.g. 'add -wire foo' will add a wire foo to all selected modules.
+
+
+    add {-wire|-input|-inout|-output} <name> <width> [selection]
+
+Add a wire (input, inout, output port) with the given name and width. The
+command will fail if the object exists already and has different properties
+than the object to be created.
+
+
+    add -global_input <name> <width> [selection]
+
+Like 'add -input', but also connect the signal between instances of the
+selected modules.
+\end{lstlisting}
+
 \section{cd -- a shortcut for 'select -module <name>'}
 \label{cmd:cd}
 \begin{lstlisting}[numbers=left,frame=single]
@@ -390,11 +415,15 @@ needed.
         also check the design hierarchy. this generates an error when
         an unknown module is used as cell type.
 
+    -keep_positionals
+        per default this pass also converts positional arguments in cells
+        to arguments using port names. this option disables this behavior.
+
     -top <module>
         use the specified top module to built a design hierarchy. modules
         outside this tree (unused modules) are removed.
 
-In -generate mode this pass generates placeholder modules for the given cell
+In -generate mode this pass generates blackbox modules for the given cell
 types (wildcards supported). For this the design is searched for cells that
 match the given types and then the given port declarations are used to
 determine the direction of the ports. The syntax for a port declaration is:
@@ -411,6 +440,32 @@ This pass ignores the current selection and always operates on all modules
 in the current design.
 \end{lstlisting}
 
+\section{iopadmap -- technology mapping of i/o pads (or buffers)}
+\label{cmd:iopadmap}
+\begin{lstlisting}[numbers=left,frame=single]
+    iopadmap [options] [selection]
+
+Map module inputs/outputs to PAD cells from a library. This pass
+can only map to very simple PAD cells. Use 'techmap' to further map
+the resulting cells to more sophisticated PAD cells.
+
+    -inpad <celltype> <portname>[:<portname>]
+        Map module input ports to the given cell type with
+        the given port name. if a 2nd portname is given, the
+        signal is passed through the pad call, using the 2nd
+        portname as output.
+
+    -outpad <celltype> <portname>[:<portname>]
+    -inoutpad <celltype> <portname>[:<portname>]
+        Similar to -inpad, but for output and inout ports.
+
+    -widthparam <param_name>
+        Use the specified parameter name to set the port width.
+
+    -nameparam <param_name>
+        Use the specified parameter to set the port name.
+\end{lstlisting}
+
 \section{ls -- list modules or objects in modules}
 \label{cmd:ls}
 \begin{lstlisting}[numbers=left,frame=single]
@@ -433,7 +488,7 @@ This pass calls all the other memory_* passes in a useful order:
     memory_map          (skipped if called with -nomap)
 
 This converts memories to word-wide DFFs and address decoders
-or moultiport memory blocks if called with the -nomap option.
+or multiport memory blocks if called with the -nomap option.
 \end{lstlisting}
 
 \section{memory\_collect -- creating multi-port memory cells}
@@ -560,28 +615,41 @@ are then merged to one cell.
 \section{proc -- translate processes to netlists}
 \label{cmd:proc}
 \begin{lstlisting}[numbers=left,frame=single]
-    proc [selection]
+    proc [options] [selection]
 
 This pass calls all the other proc_* passes in the most common order.
 
     proc_clean
     proc_rmdead
+    proc_init
     proc_arst
     proc_mux
     proc_dff
     proc_clean
 
 This replaces the processes in the design with multiplexers and flip-flops.
+
+The following options are supported:
+
+    -global_arst [!]<netname>
+        This option is passed through to proc_arst.
 \end{lstlisting}
 
 \section{proc\_arst -- detect asynchronous resets}
 \label{cmd:proc_arst}
 \begin{lstlisting}[numbers=left,frame=single]
-    proc_arst [selection]
+    proc_arst [-global_arst [!]<netname>] [selection]
 
 This pass identifies asynchronous resets in the processes and converts them
 to a different internal representation that is suitable for generating
 flip-flop cells with asynchronous resets.
+
+    -global_arst [!]<netname>
+        In modules that have a net with the given name, use this net as async
+        reset for registers that have been assign initial values in their
+        declaration ('reg foobar = constant_value;'). Use the '!' modifier for
+        active low reset signals. Note: the frontend stores the default value
+        in the 'init' attribute on the net.
 \end{lstlisting}
 
 \section{proc\_clean -- remove empty parts of processes}
@@ -602,6 +670,16 @@ This pass identifies flip-flops in the processes and converts them to
 d-type flip-flop cells.
 \end{lstlisting}
 
+\section{proc\_init -- convert initial block to init attributes}
+\label{cmd:proc_init}
+\begin{lstlisting}[numbers=left,frame=single]
+    proc_init [selection]
+
+This pass extracts the 'init' actions from processes (generated from verilog
+'initial' blocks) and sets the initial value to the 'init' attribute on the
+respective wire.
+\end{lstlisting}
+
 \section{proc\_mux -- convert decision trees to multiplexers}
 \label{cmd:proc_mux}
 \begin{lstlisting}[numbers=left,frame=single]
@@ -677,7 +755,7 @@ Verilog-2005 is supported.
         do not run the pre-processor
 
     -lib
-        only create empty placeholder modules
+        only create empty blackbox modules
 
     -noopt
         don't perform basic optimizations (such as const folding) in the
@@ -1044,6 +1122,11 @@ unless another prefix is specified using -prefix <prefix>.
 
 This command splits multi-bit nets into single-bit nets.
 
+    -format char1[char2]
+        the first char is inserted between the net name and the bit index, the
+        second char is appended to the netname. e.g. -format () creates net
+        names like 'mysignal(42)'. the default is '[]'.
+
     -ports
         also split module ports. per default only internal signals are split.
 \end{lstlisting}
@@ -1071,6 +1154,69 @@ Only objects from one module might be selected. The value of the -name option
 is used as the value of the 'submod' attribute above.
 \end{lstlisting}
 
+\section{synth\_xilinx -- synthesis for Xilinx FPGAs}
+\label{cmd:synth_xilinx}
+\begin{lstlisting}[numbers=left,frame=single]
+    synth_xilinx [options]
+
+This command runs synthesis for Xilinx FPGAs. This command does not operate on
+partly selected designs.
+
+    -top <module>
+        use the specified module as top module (default='top')
+
+    -arch <arch>
+        select architecture. the following architectures are supported:
+            spartan6 (default), artix7, kintex7, virtex7, zynq7000
+            (this parameter is not used by the command at the moment)
+
+    -edif <file>
+        write the design to the specified edif file. writing of an output file
+        is omitted if this parameter is not specified.
+
+    -run <from_label>:<to_label>
+        only run the commands between the labels (see below). an empty
+        from label is synonymous to 'begin', and empty to label is
+        synonymous to the end of the command list.
+
+
+The following commands are executed by this synthesis command:
+
+    begin:
+        hierarchy -check -top <top>
+
+    coarse:
+        proc
+        opt
+        memory
+        clean
+        fsm
+        opt
+
+    fine:
+        techmap
+        opt
+
+    map_luts:
+        abc -lut 6
+        clean
+
+    map_cells:
+        techmap -map <share_dir>/xilinx/cells.v
+        clean
+
+    clkbuf:
+        select -set xilinx_clocks <top>/t:FDRE %x:+FDRE[C] <top>/t:FDRE %d
+        iopadmap -inpad BUFGP O:I @xilinx_clocks
+
+    iobuf:
+        select -set xilinx_nonclocks <top>/w:* <top>/t:BUFGP %x:+BUFGP[I] %d
+        iopadmap -outpad OBUF I:O -inpad IBUF O:I @xilinx_nonclocks
+
+    edif:
+        write_edif -top <top> synth.edif
+\end{lstlisting}
+
 \section{tcl -- execute a TCL script file}
 \label{cmd:tcl}
 \begin{lstlisting}[numbers=left,frame=single]
@@ -1143,6 +1289,39 @@ value after initialization. This can e.g. be used to force a reset signal
 low in order to explore more inner states in a state machine.
 \end{lstlisting}
 
+\section{write\_blif -- write design to BLIF file}
+\label{cmd:write_blif}
+\begin{lstlisting}[numbers=left,frame=single]
+    write_blif [options] [filename]
+
+Write the current design to an BLIF file.
+
+    -top top_module
+        set the specified module as design top module
+
+    -buf <cell-type> <in-port> <out-port>
+        use cells of type <cell-type> with the specified port names for buffers
+
+    -true <cell-type> <out-port>
+    -false <cell-type> <out-port>
+        use the specified cell types to drive nets that are constant 1 or 0
+
+The following options can be usefull when the generated file is not going to be
+read by a BLIF parser but a custom tool. It is recommended to not name the output
+file *.blif when any of this options is used.
+
+    -subckt
+        do not translate Yosys's internal gates to generic BLIF logic
+        functions. Instead create .subckt lines for all cells.
+
+    -conn
+        do not generate buffers for connected wires. instead use the
+        non-standard .conn statement.
+
+    -impltf
+        do not write definitions for the $true and $false wires.
+\end{lstlisting}
+
 \section{write\_edif -- write design to EDIF netlist file}
 \label{cmd:write_edif}
 \begin{lstlisting}[numbers=left,frame=single]
@@ -1152,6 +1331,11 @@ Write the current design to an EDIF netlist file.
 
     -top top_module
         set the specified module as design top module
+
+Unfortunately there are different "flavors" of the EDIF file format. This
+command generates EDIF files for the Xilinx place&route tools. It might be
+necessary to make small modifications to this command when a different tool
+is targeted.
 \end{lstlisting}
 
 \section{write\_ilang -- write design to ilang file}
@@ -1236,9 +1420,9 @@ Write the current design to a verilog file.
         without this option all internal cells are converted to verilog
         expressions.
 
-    -placeholders
-        usually modules with the 'placeholder' attribute are ignored. with
-        this option set only the modules with the 'placeholder' attribute
+    -blackboxes
+        usually modules with the 'blackbox' attribute are ignored. with
+        this option set only the modules with the 'blackbox' attribute
         are written to the output file.
 
     -selected