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