Refine language design document

[dalance]

The current documentation is not sufficiant to describe the diffrences from the existing works. So I think it should be replaced.
This is a candidate for the description in README.md and the top page of https://doc.veryl-lang.org/book.
Please comment if there are any improvements.

---

Gradual evolution in RTL development by Veryl

Veryl is a hardware description language designed as "SystemVerilog alternative". Especially we focus on gradually improving the existing Verilog/SystemVerilog codebase.

"Gradual" means that a part of the existing codebase can be replaced to Veryl gradually. Necessarily Veryl has high interoperability to SystemVerilog. Veryl assures the replaced codebase is synthesizable and no-mismatch between simulation and synthesis, and provides real-time editing support through editor plugins. Additionally the libraries of Veryl can be added as dependencies through the integrated build tool.

In the following, we see "what is provided by Veryl" and "what is not provided by Veryl" to make differences from SystemVerilog and the existing Alt-HDLs clear.

What is provided by Veryl?

Sophisticated syntax

The syntax of Veryl is extracted from synthesizable description of SystemVerilog, and syntax improvements achieved by modern programming languages like Rust are added. Deprecated descriptions of SystemVerilog are already removed from the syntax.

Veryl

SystemVerilog

/// documentation comment by markdown format /// * list item1 /// * list item2 pub module Delay #( param WIDTH: u32 = 1, // trailing comma is allowed ) ( i_clk : input logic , i_rst : input logic , i_data: input logic<WIDTH>, o_data: input logic<WIDTH>, ) { // unused variable which is not started with `_` are warned var _unused_variable: logic; always_ff (i_clk, i_rst) { // abstraction syntax of reset polarity and synchronicity if_reset { o_data = '0; } else { o_data = i_data; } } }

// comment // // module Delay #( parameter int WIDTH = 1 ) ( input i_clk , input i_rst , input [WIDTH-1:0] i_data, output [WIDTH-1:0] o_data ); logic unused_variable; always_ff @ (posedge i_clk or negedge i_rst) begin if (!i_rst) begin o_data <= '0; end else begin o_data <= i_data; end end endmodule

The above is comparison between Veryl and SystemVerilog.

• If documentation comments which are started by /// are added, Veryl compiler can generate documentation automatically.
• Allowing trailing comma eases re-order list and suppresses unnecessary differences on version control system like git.
• _ prefix can make unused variable clear, and no-prefix unused variables are warned by Veryl compiler.
• if_reset syntax can abstract reset polarity and synchronicity, Veryl compiler can select them at code generation.

Real-time feedback

Veryl compiler provides real-time feedback of syntax error and lint error through editor plugins.
The problematic descriptions can be fixed instantlly without simulation or synthesis process which consume time.
And auto-formatting feature enables to keep a consistent format through whole codebase.

Interoperability to SystemVerilog

Veryl has the almost same semantics as SystemVerilog, and Veryl compiler generates human-readable SystemVerilog source code.
So it can be replaced a part of the existing SystemVerilog codebase, or cooperated to them.

What is not provided by Veryl?

Short-handed code

Some existing alt-HDLs seems to focus on shorting dramatically the existing Verilog/SystemVerilog source code, but Veryl doesn't adopt the way. Generating broad Verilog/SystemVerilog code from the shorten code causes difficulty of code debug and adjustment. Instead of it, Veryl slightly shorten the redundant syntax of SystemVerilog with keeping explicity of the meaning.

Simulation description

Simulation description has widely different domain from synthesizable RTL development. Not just simple delay syntax but also complicated assertion and hierarchical verification framework are required. So Veryl doesn't support them directly, and support verification through integration of the testbenches which are written by other languages like SystemVerilog and Python.

[nblei]

Looks good. There are a few grammar mistakes which will be easy to fix in a README.md file, but a bit of a nuisance to fix in an issues thread.

[nblei]

https://github.com/TerosTechnology/vscode-terosHDL

Also, I think it may be useful to look at TerosHDL to both distinguish Veryl from it, and also perhaps incorporate some if its ideas.

[dalance]

Looks good. There are a few grammar mistakes which will be easy to fix in a README.md file, but a bit of a nuisance to fix in an issues thread.

Thanks! I think grammar mistakes can be fixed after update of documents.
I'll check TerosHDL later.

[dalance]

I've updated the overview of https://veryl-lang.org based on the discussion in #575.

[saturn77]

The new website at https://veryl-lang.org looks very good.

I think it is important that Veryl does not not have a "pipeline" command or directive. Newer HDL's like Spade (www.spade-lang.org) have this feature, which to me starts to introduce issues in the generated code although it is potentially a nice feature.

I think it's very worthwhile noting that that Veryl generates human readable and well organized SystemVerilog code, not an obfuscated version of SystemVerilog that many other HDL's generate.

It may be worthwhile to make a comparison between Veryl and other languages like Amaranth, Silice, Chisel, and Spade.

Perhaps a motto of Veryl is "evolved SystemVerilog using modern software tools" . . . .

[dalance]

I'm planning to create a page listing the syntactic advantages to SystemVerilog. I've listed some points for now, but please let me know if there are any other aspects I should include:

• Trailing comma
• Abstract syntax for clock reset
• Omission notation for same-name connections
• Documentation comments including wavedrom support
• Assignment operators usable with always_ff
• Namespace separation for enum variants
• Repeat syntax for bit concatenation
• if/case expressions
• Half-open, closed interval notation (and range-based for/inside)
• msb/lsb
• outside expression
• Intermediate variable binding with let statements usable anywhere
• Named blocks
• Visibility control
• Check for unused, undeclared, unassigned variables (explicit indication with _)

[dalance]

I've added a page to the book.

https://doc.veryl-lang.org/book/02_features.html

[saturn77]

The page added to the book is very good and helpful. The page systematically highlights the advantages of Veryl.

Veryl's integrated tooling and clean design with rust syntax are the compelling reasons why I am using Veryl.