Merge updates from 'master' into krys/docs

docs/source/yosys_internals/formats/cell_library.rst

@@ -630,6 +630,133 @@ Add information about ``$assert``, ``$assume``, ``$live``, ``$fair``,
 
 Add information about ``$ff`` and ``$_FF_`` cells.
 
+Debugging cells
+~~~~~~~~~~~~~~~
+
+The ``$print`` cell is used to log the values of signals, akin to (and
+translatable to) the ``$display`` and ``$write`` family of tasks in Verilog.  It
+has the following parameters:
+
+``\FORMAT``
+	The internal format string.  The syntax is described below.
+
+``\ARGS_WIDTH``
+	The width (in bits) of the signal on the ``\ARGS`` port.
+
+``\TRG_ENABLE``
+	True if triggered on specific signals defined in ``\TRG``; false if
+	triggered whenever ``\ARGS`` or ``\EN`` change and ``\EN`` is 1.
+
+If ``\TRG_ENABLE`` is true, the following parameters also apply:
+
+``\TRG_WIDTH``
+	The number of bits in the ``\TRG`` port.
+
+``\TRG_POLARITY``
+	For each bit in ``\TRG``, 1 if that signal is positive-edge triggered, 0 if
+	negative-edge triggered.
+
+``\PRIORITY``
+	When multiple ``$print`` cells fire on the same trigger, they execute in
+	descending priority order.
+
+Ports:
+
+``\TRG``
+	The signals that control when this ``$print`` cell is triggered.
+
+``\EN``
+	Enable signal for the whole cell.
+
+``\ARGS``
+	The values to be displayed, in format string order.
+
+Format string syntax
+^^^^^^^^^^^^^^^^^^^^
+
+The format string syntax resembles Python f-strings.  Regular text is passed
+through unchanged until a format specifier is reached, starting with a ``{``.
+
+Format specifiers have the following syntax.  Unless noted, all items are
+required:
+
+``{``
+	Denotes the start of the format specifier.
+
+size
+	Signal size in bits; this many bits are consumed from the ``\ARGS`` port by
+	this specifier.
+
+``:``
+	Separates the size from the remaining items.
+
+justify
+	``>`` for right-justified, ``<`` for left-justified.
+
+padding
+	``0`` for zero-padding, or a space for space-padding.
+
+width\ *?*
+	(optional) The number of characters wide to pad to.
+
+base
+	* ``b`` for base-2 integers (binary)
+	* ``o`` for base-8 integers	(octal)
+	* ``d`` for base-10 integers (decimal)
+	* ``h`` for base-16	integers (hexadecimal)
+	* ``c`` for ASCII characters/strings
+	* ``t`` and ``r`` for simulation time (corresponding to :verilog:`$time` and :verilog:`$realtime`)
+
+For integers, this item may follow:
+
+``+``\ *?*
+	(optional, decimals only) Include a leading plus for non-negative numbers.
+	This can assist with symmetry with negatives in tabulated output.
+
+signedness
+	``u`` for unsigned, ``s`` for signed.  This distinction is only respected
+	when rendering decimals.
+
+ASCII characters/strings have no special options, but the signal size must be
+divisible by 8.
+
+For simulation time, the signal size must be zero.
+
+Finally:
+
+``}``
+	Denotes the end of the format specifier.
+
+Some example format specifiers:
+
++ ``{8:>02hu}`` - 8-bit unsigned integer rendered as hexadecimal,
+  right-justified, zero-padded to 2 characters wide.
++ ``{32:< 15d+s}`` - 32-bit signed integer rendered as decimal, left-justified,
+  space-padded to 15 characters wide, positive values prefixed with ``+``.
++ ``{16:< 10hu}`` - 16-bit unsigned integer rendered as hexadecimal,
+  left-justified, space-padded to 10 characters wide.
++ ``{0:>010t}`` - simulation time, right-justified, zero-padded to 10 characters
+  wide.
+
+To include literal ``{`` and ``}`` characters in your format string, use ``{{``
+and ``}}`` respectively.
+
+It is an error for a format string to consume more or less bits from ``\ARGS``
+than the port width.
+
+Values are never truncated, regardless of the specified width.
+
+Note that further restrictions on allowable combinations of options may apply
+depending on the backend used.
+
+For example, Verilog does not have a format specifier that allows zero-padding a
+string (i.e. more than 1 ASCII character), though zero-padding a single
+character is permitted.
+
+Thus, while the RTLIL format specifier ``{8:>02c}`` translates to ``%02c``,
+``{16:>02c}`` cannot be represented in Verilog and will fail to emit.  In this
+case, ``{16:> 02c}`` must be used, which translates to ``%2s``.
+
 .. _sec:celllib_gates:
 
 Gates