From dad78d5258b5f7a7f2771002368b7cd771b0e7a4 Mon Sep 17 00:00:00 2001 From: Martin Whitaker Date: Sun, 3 Aug 2025 18:19:45 +0100 Subject: [PATCH] Move details of non-standard behaviour from README to Documentation. Some of this was duplicated in the documentation, some of it was only in the README. Let's have it all in one place, linked to from the README. --- .../usage/icarus_verilog_extensions.rst | 47 +++++- Documentation/usage/icarus_verilog_quirks.rst | 57 +++++++ README.md | 141 +----------------- 3 files changed, 105 insertions(+), 140 deletions(-) diff --git a/Documentation/usage/icarus_verilog_extensions.rst b/Documentation/usage/icarus_verilog_extensions.rst index 5abf1ab26..62caeae6a 100644 --- a/Documentation/usage/icarus_verilog_extensions.rst +++ b/Documentation/usage/icarus_verilog_extensions.rst @@ -7,15 +7,52 @@ standard. Some of these are picked from extended variants of the language, such as SystemVerilog, and some are expressions of internal behavior of Icarus Verilog, made available as a tool debugging aid. -Built-in System Functions -------------------------- +Don't use any of these extensions if you want to keep your code portable +across other Verilog compilers. + +System Functions +---------------- + +``$is_signed()`` +^^^^^^^^^^^^^^^^^^^^^^ + +This function returns 1 if the expression contained is signed, or 0 otherwise. +This is mostly of use for compiler regression tests. + +``$bits()``, ``$sizeof()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``$bits`` system function returns the size in bits of the expression that +is its argument. The result of this function is undefined if the argument +doesn't have a self-determined size. + +The ``$sizeof`` system function is deprecated in favour of ``$bits``, which is +the same thing, but included in the SystemVerilog definition. + +``$simtime()`` +^^^^^^^^^^^^^^ + +This returns as a 64bit value the simulation time, unscaled by the time units +of the local scope. This is different from the ``$time`` and ``$stime`` +functions which return the scaled times. This function is added for regression +testing of the compiler and run time, but can be used by applications who +really want the simulation time. + +Note that the simulation time can be confusing if there are lots of different +```timescales`` within a design. It is not in general possible to predict +what the simulation precision will turn out to be. + +``$mti_random()``, ``$mti_dist_uniform`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These functions are similar to the IEEE 1364 standard ``$random`` functions, +but they use the Mersenne Twister (MT19937) algorithm. This is considered an +excellent random number generator, but does not generate the same sequence as +the standardized ``$random``. System Tasks ------------ -These are system tasks that are unique to Icarus Verilog. Don't use any of -these if you want to keep your code portable across other Verilog compilers. - ``$readmempath`` ^^^^^^^^^^^^^^^^ diff --git a/Documentation/usage/icarus_verilog_quirks.rst b/Documentation/usage/icarus_verilog_quirks.rst index 2aee056f1..d7c11d8ca 100644 --- a/Documentation/usage/icarus_verilog_quirks.rst +++ b/Documentation/usage/icarus_verilog_quirks.rst @@ -352,6 +352,25 @@ will produce the following output: This is g and f: 0.123, 0.123. This is more g and f: 1.23, 1.235. +``%t`` Time Format Specifier Can Specify Width +---------------------------------------------- + +Standard Verilog does not allow width fields in the ``%t`` formats of display +strings. For example, this is illegal: + +.. code-block:: verilog + + $display("Time is %0t", $time); + +Standard Verilog instead relies on the ``$timeformat`` to completely specify +the format. + +Icarus Verilog allows the programmer to specify the field width. The ``%t`` +format in Icarus Verilog works exactly as it does in standard Verilog. +However, if the programmer chooses to specify a minimum width (i.e., ``%5t``), +then for that display Icarus Verilog will override the ``$timeformat`` minimum +width and use the explicit minimum width. + ``%v`` Format Specifier Can Display Vectors ------------------------------------------- @@ -379,3 +398,41 @@ a repeat event control should do. In Icarus Verilog the ``repeat`` statement is consistent with the repeat event control definition. If the argument is signed and is a negative value this will be treated the same as an argument value of 0. + +Built-in System Functions May Be Evaluated at Compile Time +---------------------------------------------------------- + +Certain of the system functions have well-defined meanings, so can +theoretically be evaluated at compile-time, instead of using runtime VPI +code. Doing so means that VPI cannot override the definitions of functions +handled in this manner. On the other hand, this makes them synthesizable, +and also allows for more aggressive constant propagation. The functions +handled in this manner are: + +- ``$bits`` +- ``$signed`` +- ``$sizeof`` +- ``$unsigned`` + +Implementations of these system functions in VPI modules will be ignored. + +``vpiScope`` Iterator on ``vpiScope`` Objects +--------------------------------------------- + +In the VPI, the normal way to iterate over ``vpiScope`` objects contained +within a ``vpiScope`` object, is the ``vpiInternalScope`` iterator. Icarus +Verilog adds support for the ``vpiScope`` iterator of a ``vpiScope`` object, +that iterates over *everything* that is contained in the current scope. This +is useful in cases where one wants to iterate over all the objects in a scope +without iterating over all the contained types explicitly. + +Time 0 Race Resolution +---------------------- + +Combinational logic is routinely modelled using always blocks. However, this +can lead to race conditions if the inputs to the combinational block are +initialized in initial statements. Icarus Verilog slightly modifies time 0 +scheduling by arranging for always statements with ANYEDGE sensitivity lists +to be scheduled before any other threads. This causes combinational always +blocks to be triggered when the values in the sensitivity list are initialized +by initial threads. diff --git a/README.md b/README.md index ce8b57db0..91971210c 100644 --- a/README.md +++ b/README.md @@ -407,142 +407,13 @@ constructs. The list of unsupported SystemVerilog constructs is too large to enumerate here. -## Nonstandard Constructs or Behaviors - -Icarus Verilog includes some features that are not part of the -IEEE1364 standard, but have well-defined meaning, and also sometimes -gives nonstandard (but extended) meanings to some features of the -language that are defined. See the "extensions.txt" documentation for -more details. - -* `$is_signed()` - - This system function returns 1 if the expression contained is - signed, or 0 otherwise. This is mostly of use for compiler - regression tests. - -* `$sizeof()`, `$bits()` - - The `$bits` system function returns the size in bits of the - expression that is its argument. The result of this - function is undefined if the argument doesn't have a - self-determined size. - - The `$sizeof` function is deprecated in favour of `$bits`, which is - the same thing, but included in the SystemVerilog definition. - -* `$simtime` - - The `$simtime` system function returns as a 64bit value the - simulation time, unscaled by the time units of local - scope. This is different from the $time and $stime functions - which return the scaled times. This function is added for - regression testing of the compiler and run time, but can be - used by applications who really want the simulation time. - - Note that the simulation time can be confusing if there are - lots of different `` `timescales`` within a design. It is not in - general possible to predict what the simulation precision will - turn out to be. - -* `$mti_random()`, `$mti_dist_uniform` - - These functions are similar to the IEEE1364 standard $random - functions, but they use the Mersenne Twister (MT19937) - algorithm. This is considered an excellent random number - generator, but does not generate the same sequence as the - standardized $random. - -### Builtin system functions - -Certain of the system functions have well-defined meanings, so -can theoretically be evaluated at compile-time, instead of -using runtime VPI code. Doing so means that VPI cannot -override the definitions of functions handled in this -manner. On the other hand, this makes them synthesizable, and -also allows for more aggressive constant propagation. The -functions handled in this manner are: - -* `$bits` -* `$signed` -* `$sizeof` -* `$unsigned` - -Implementations of these system functions in VPI modules will be ignored. - -### Preprocessing Library Modules - -Icarus Verilog does preprocess modules that are loaded from -libraries via the -y mechanism. However, the only macros -defined during the compilation of that file are those that it -defines itself (or includes) or that are defined in the -command line or command file. - -Specifically, macros defined in the non-library source files -are not remembered when the library module is loaded. This is -intentional. If it were otherwise, then compilation results -might vary depending on the order that libraries are loaded, -and that is too unpredictable. - -It is said that some commercial compilers do allow macro -definitions to span library modules. That's just plain weird. - -### Width in `%t` Time Formats - -Standard Verilog does not allow width fields in the %t formats -of display strings. For example, this is illegal: - -``` - $display("Time is %0t", $time); -``` - -Standard Verilog instead relies on the $timeformat to -completely specify the format. - -Icarus Verilog allows the programmer to specify the field -width. The `%t` format in Icarus Verilog works exactly as it -does in standard Verilog. However, if the programmer chooses -to specify a minimum width (i.e., `%5t`), then for that display -Icarus Verilog will override the `$timeformat` minimum width and -use the explicit minimum width. - -### vpiScope Iterator on vpiScope Objects - -In the VPI, the normal way to iterate over vpiScope objects -contained within a vpiScope object, is the vpiInternalScope -iterator. Icarus Verilog adds support for the vpiScope -iterator of a vpiScope object, that iterates over *everything* -the is contained in the current scope. This is useful in cases -where one wants to iterate over all the objects in a scope -without iterating over all the contained types explicitly. - -### Time 0 Race Resolution - -Combinational logic is routinely modelled using always -blocks. However, this can lead to race conditions if the -inputs to the combinational block are initialized in initial -statements. Icarus Verilog slightly modifies time 0 scheduling -by arranging for always statements with ANYEDGE sensitivity -lists to be scheduled before any other threads. This causes -combinational always blocks to be triggered when the values in -the sensitivity list are initialized by initial threads. - -### Nets with Types - -Icarus Verilog supports an extended syntax that allows nets -and regs to be explicitly typed. The currently supported types -are logic, bool and real. This implies that `logic` and `bool` -are new keywords. Typical syntax is: - -```verilog - wire real foo = 1.0; - reg logic bar, bat; -``` -... and so forth. The syntax can be turned off by using the -`-gxtypes` flag to iverilog, and turned on explicitly with the -`-gno-xtypes flag to iverilog. Note that this applies to standard -Verilog; SystemVerilog allows similar syntax. +## Nonstandard Constructs and Behaviors +Icarus Verilog includes some features that are not part of the IEEE 1364 +standard, but have well-defined meaning, and also sometimes gives nonstandard +(but extended) meanings to some features of the language that are defined. +See the "Icarus Verilog Extensions" and "Icarus Verilog Quirks" sections at +https://steveicarus.github.io/iverilog/ for more details. ## Credits